jules-orchestrator-kit 0.28.1 → 0.29.0

package/bin/agentctl.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
 import { parseArgs } from "node:util";
-import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { readFileSync, existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { loadConfig, resolveRoot, detectStack, bootstrapZeroTestRepo } 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 { acquireLock, releaseLock, lockStatus, checkDailyBudget, getQueueDir } from "../src/state.mjs";
 import { worktreePrune } from "../src/git.mjs";
 import { reapOrphanedIntents, reapStaleMutexDirs } from "../src/journal.mjs";
 
@@ -14,7 +14,7 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.28.1 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.29.0 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -30,7 +30,8 @@ Commands:
   bootstrap             Bootstrap zero-test repository with verification oracle
   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
+  init                  Scaffold .agent/ config and run onboarding wizard
+  task create           Interactively author and scope a Jules task envelope
   status                Display queue and system status summary
   scan                  Scan codebase for TODO/FIXME task candidates
   version               Output agentctl version
@@ -53,7 +54,7 @@ async function main() {
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
-    console.log("agentctl v0.28.1");
+    console.log("agentctl v0.29.0");
     process.exit(0);
   }
 
@@ -264,7 +265,7 @@ async function main() {
     }
 
     case "doctor": {
-      console.log(`\n🔍 agentctl System Diagnostics (v0.28.1)`);
+      console.log(`\n🔍 agentctl System Diagnostics (v0.29.0)`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Config File      : ${config._file || "None (Using defaults)"}`);
@@ -326,34 +327,81 @@ async function main() {
     }
 
     case "init": {
-      const agentDir = join(root, ".agent");
-      ensureDir(agentDir);
-      const configPath = join(agentDir, "config.yml");
-      if (!existsSync(configPath)) {
-        writeFileSync(
-          configPath,
-          `version: 1
-provider: jules
-limits:
-  diff_kb: 75
-  daily_tasks: 300
-branch_prefix: agent/
-base_branch: main
-`,
-          "utf-8"
-        );
-        console.log(`✅ Created .agent/config.yml`);
+      const { values } = parseArgs({
+        args: args.slice(1),
+        options: {
+          interactive: { type: "boolean", short: "i" },
+          tier: { type: "string", short: "t" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+
+      const { runInitWizard } = await import("../src/wizard-init.mjs");
+      const res = await runInitWizard(root, {
+        interactive: values.interactive !== false,
+        tier: values.tier || "pro",
+      });
+
+      if (values.json) {
+        console.log(JSON.stringify(res, null, 2));
       } else {
-        console.log(`ℹ️ .agent/config.yml already exists.`);
+        console.log(`✅ Onboarding complete! Manifest generated at ${res.configPath}`);
+        console.log(`   Tier: ${res.plan.tier.toUpperCase()} (${res.plan.limits.concurrency} worker(s), ${res.plan.limits.daily_tasks} daily tasks)`);
+        console.log(`   Verification Test Command : "${res.plan.verify.test}"`);
+        console.log(`   Active Presets            : ${res.plan.presets.join(", ")}`);
       }
       process.exit(0);
       break;
     }
 
+    case "task": {
+      const subCommand = args[1] || "create";
+      if (subCommand === "create") {
+        const { values } = parseArgs({
+          args: args.slice(2),
+          options: {
+            title: { type: "string", short: "t" },
+            prompt: { type: "string", short: "p" },
+            "verify-cmd": { type: "string", short: "v" },
+            "auto-pr": { type: "boolean" },
+            "require-plan-approval": { type: "boolean" },
+            repoless: { type: "boolean" },
+            json: { type: "boolean", short: "j" },
+          },
+          allowPositionals: true,
+        });
+
+        const { runTaskCreateWizard } = await import("../src/wizard-task.mjs");
+        const res = await runTaskCreateWizard(root, {
+          title: values.title,
+          prompt: values.prompt,
+          verifyCmd: values["verify-cmd"],
+          autoPr: values["auto-pr"],
+          requirePlanApproval: values["require-plan-approval"],
+          repoless: values.repoless,
+        });
+
+        if (values.json) {
+          console.log(JSON.stringify(res, null, 2));
+        } else {
+          console.log(`✅ Task synthesized & queued at ${res.taskFile}`);
+          console.log(`   Task ID  : ${res.plan.taskId}`);
+          console.log(`   Title    : ${res.plan.title}`);
+          console.log(`   Auto-PR  : ${res.plan.flags.autoPr}`);
+        }
+        process.exit(0);
+      } else {
+        console.error(`Unknown task subcommand '${subCommand}'. Supported: agentctl task create`);
+        process.exit(1);
+      }
+      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.1)`);
+      console.log(`\n📊 agentctl Status Summary (v0.29.0)`);
       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.28.1)
+ * Google Jules Orchestrator Kit - Node.js SDK (v0.29.0)
  *
  * Exposes core orchestrator functions for programmatically driving agent tasks,
  * security auditing, repo gating, and state operations.
@@ -73,3 +73,16 @@ export { getDynamicGuardrails, dispatchTask } from "./scripts/jules-dispatch.mjs
 export { classifyQueueFailure } from "./scripts/jules-queue-runner.mjs";
 export { extractPrUrls, auditSessions, buildSyncManifest, pushReservationManifest } from "./scripts/utils.mjs";
 
+// Native TUI Primitives
+export { isTTY, styleText, select, multiSelect, input, confirm, secretInput, spinner, ANSI } from "./src/tui.mjs";
+
+// Stack Oracle & Verification Probes
+export { detectStackOracles, runVerificationProbe } from "./src/wizard-oracle.mjs";
+
+// Onboarding & Presets Engine
+export { planInit, loadPresets, runInitWizard, TIER_PROFILES, BUILTIN_PRESETS } from "./src/wizard-init.mjs";
+
+// Guided Task Authoring Subsystem
+export { planTaskCreate, runTaskCreateWizard, GUARDRAIL_FOOTER } from "./src/wizard-task.mjs";
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "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.28.1)</h1>
+  <h1>🚀 jules-orchestrator-kit Dashboard (v0.29.0)</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.28.1", root, ts: new Date().toISOString() }));
+      return res.end(JSON.stringify({ ok: true, version: "0.29.0", root, ts: new Date().toISOString() }));
     }
 
     if (url.pathname === "/api/telemetry") {

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 });

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

package/src/provider.mjs

@@ -121,16 +121,23 @@ export function createProvider(spec = "jules", config = {}) {
         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}`)
-        : "sources/github/default/repo";
+        : 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"),
-        source: sourceName,
+        branch: startingBranch,
+        source: sourceName || "",
         project: process.env.JULES_PROJECT_ID || "default",
         ...ctx,
       };
@@ -176,9 +183,15 @@ export function createProvider(spec = "jules", config = {}) {
         }
 
         if (bodyObj && typeof bodyObj === "object") {
-          if (data.repoless || ctx.repoless || task.repoless) {
+          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);
         }
 

package/src/tui.mjs

@@ -0,0 +1,407 @@
+import { createInterface } from "node:readline/promises";
+import { isatty } from "node:tty";
+
+// ANSI Styling & Escapes
+export const ANSI = {
+  reset: "\u001b[0m",
+  bold: "\u001b[1m",
+  dim: "\u001b[2m",
+  red: "\u001b[31m",
+  green: "\u001b[32m",
+  yellow: "\u001b[33m",
+  blue: "\u001b[34m",
+  cyan: "\u001b[36m",
+  white: "\u001b[37m",
+  bgCyan: "\u001b[46m",
+  bgBlue: "\u001b[44m",
+  hideCursor: "\u001b[?25l",
+  showCursor: "\u001b[?25h",
+  clearLine: "\u001b[2K\r",
+  cursorUp: (n = 1) => `\u001b[${n}A`,
+  cursorDown: (n = 1) => `\u001b[${n}B`,
+};
+
+/**
+ * Check if the given input stream is an interactive TTY terminal.
+ * @param {import("node:stream").Readable} [stream]
+ * @returns {boolean}
+ */
+export function isTTY(stream = process.stdin) {
+  return Boolean(stream && (stream.isTTY || isatty(stream.fd)));
+}
+
+/**
+ * Format string with ANSI styling if stream supports TTY.
+ * @param {string} text
+ * @param {string} style
+ * @returns {string}
+ */
+export function styleText(text, style) {
+  if (!style) return text;
+  return `${style}${text}${ANSI.reset}`;
+}
+
+/**
+ * Read keypress in raw mode from TTY input stream.
+ * @param {import("node:stream").Readable} stream
+ * @returns {AsyncGenerator<string, void, unknown>}
+ */
+async function* readKeypresses(stream = process.stdin) {
+  const wasRaw = stream.isRaw;
+  if (stream.setRawMode) {
+    stream.setRawMode(true);
+  }
+  stream.resume();
+  stream.setEncoding("utf-8");
+
+  try {
+    for await (const chunk of stream) {
+      const str = String(chunk);
+      if (str === "\u0003") {
+        // Ctrl+C SIGINT
+        process.stdout.write(ANSI.showCursor + "\n");
+        process.exit(130);
+      }
+      yield str;
+    }
+  } finally {
+    if (stream.setRawMode) {
+      stream.setRawMode(Boolean(wasRaw));
+    }
+  }
+}
+
+/**
+ * Single-select interactive menu using TTY raw mode.
+ * @param {Array<{ label: string, value: any, description?: string }>} options
+ * @param {string} prompt
+ * @param {object} [opts]
+ * @returns {Promise<any>}
+ */
+export async function select(options, prompt, opts = {}) {
+  const stdin = opts.stdin || process.stdin;
+  const stdout = opts.stdout || process.stdout;
+
+  if (options.length === 0) {
+    throw new Error("select() requires at least one option.");
+  }
+
+  const defaultIdx = opts.defaultIdx ?? 0;
+  let currentIdx = Math.max(0, Math.min(options.length - 1, defaultIdx));
+
+  if (!isTTY(stdin)) {
+    // Non-TTY Headless fallback
+    if (opts.fallbackValue !== undefined) {
+      return opts.fallbackValue;
+    }
+    const val = options[currentIdx].value;
+    stdout.write(`[Headless Select] ${prompt}: Auto-selected default [${options[currentIdx].label}]\n`);
+    return val;
+  }
+
+  function render(isFinal = false) {
+    let out = `${ANSI.bold}${ANSI.cyan}?${ANSI.reset} ${ANSI.bold}${prompt}${ANSI.reset}\n`;
+    options.forEach((opt, idx) => {
+      const isSelected = idx === currentIdx;
+      const cursor = isSelected ? `${ANSI.cyan}❯${ANSI.reset}` : " ";
+      const label = isSelected ? `${ANSI.bold}${ANSI.cyan}${opt.label}${ANSI.reset}` : opt.label;
+      const desc = opt.description ? ` ${ANSI.dim}(${opt.description})${ANSI.reset}` : "";
+      out += `  ${cursor} ${label}${desc}\n`;
+    });
+    if (!isFinal) {
+      out += `${ANSI.dim}  (Use arrow keys or 1-${Math.min(9, options.length)} to select, Enter to confirm)${ANSI.reset}`;
+    }
+    return out;
+  }
+
+  stdout.write(ANSI.hideCursor);
+  let renderedLines = options.length + 2;
+  stdout.write(render());
+
+  try {
+    for await (const key of readKeypresses(stdin)) {
+      if (key === "\r" || key === "\n") {
+        // Confirm selection
+        stdout.write(ANSI.cursorUp(renderedLines) + ANSI.clearLine);
+        for (let i = 0; i < renderedLines; i++) {
+          stdout.write(ANSI.clearLine + ANSI.cursorDown(1));
+        }
+        stdout.write(ANSI.cursorUp(renderedLines));
+        stdout.write(`${ANSI.green}✔${ANSI.reset} ${ANSI.bold}${prompt}${ANSI.reset} ${ANSI.cyan}${options[currentIdx].label}${ANSI.reset}\n`);
+        return options[currentIdx].value;
+      }
+
+      let moved = false;
+      if (key === "\u001b[A" || key === "k") {
+        // Up
+        currentIdx = (currentIdx - 1 + options.length) % options.length;
+        moved = true;
+      } else if (key === "\u001b[B" || key === "j") {
+        // Down
+        currentIdx = (currentIdx + 1) % options.length;
+        moved = true;
+      } else if (/^[1-9]$/.test(key)) {
+        const num = parseInt(key, 10) - 1;
+        if (num < options.length) {
+          currentIdx = num;
+          moved = true;
+        }
+      }
+
+      if (moved) {
+        stdout.write(ANSI.cursorUp(renderedLines));
+        stdout.write(render());
+      }
+    }
+  } finally {
+    stdout.write(ANSI.showCursor);
+  }
+}
+
+/**
+ * Multi-select checkbox menu using TTY raw mode.
+ * @param {Array<{ label: string, value: any, checked?: boolean, description?: string }>} options
+ * @param {string} prompt
+ * @param {object} [opts]
+ * @returns {Promise<Array<any>>}
+ */
+export async function multiSelect(options, prompt, opts = {}) {
+  const stdin = opts.stdin || process.stdin;
+  const stdout = opts.stdout || process.stdout;
+
+  const selections = new Set();
+  options.forEach((opt, idx) => {
+    if (opt.checked) selections.add(idx);
+  });
+
+  if (!isTTY(stdin)) {
+    // Non-TTY Headless fallback
+    const selectedVals = options.filter((_, idx) => selections.has(idx)).map((o) => o.value);
+    stdout.write(`[Headless MultiSelect] ${prompt}: Auto-selected ${selectedVals.length} item(s)\n`);
+    return selectedVals;
+  }
+
+  let currentIdx = 0;
+  let renderedLines = options.length + 2;
+
+  function render() {
+    let out = `${ANSI.bold}${ANSI.cyan}?${ANSI.reset} ${ANSI.bold}${prompt}${ANSI.reset}\n`;
+    options.forEach((opt, idx) => {
+      const isHover = idx === currentIdx;
+      const isChecked = selections.has(idx);
+      const cursor = isHover ? `${ANSI.cyan}❯${ANSI.reset}` : " ";
+      const box = isChecked ? `${ANSI.green}[x]${ANSI.reset}` : `${ANSI.dim}[ ]${ANSI.reset}`;
+      const label = isHover ? `${ANSI.bold}${opt.label}${ANSI.reset}` : opt.label;
+      const desc = opt.description ? ` ${ANSI.dim}(${opt.description})${ANSI.reset}` : "";
+      out += `  ${cursor} ${box} ${label}${desc}\n`;
+    });
+    out += `${ANSI.dim}  (Space to toggle, 'a' select all, 'n' select none, Enter to confirm)${ANSI.reset}`;
+    return out;
+  }
+
+  stdout.write(ANSI.hideCursor);
+  stdout.write(render());
+
+  try {
+    for await (const key of readKeypresses(stdin)) {
+      if (key === "\r" || key === "\n") {
+        const resultVals = options.filter((_, idx) => selections.has(idx)).map((o) => o.value);
+        stdout.write(ANSI.cursorUp(renderedLines));
+        for (let i = 0; i < renderedLines; i++) {
+          stdout.write(ANSI.clearLine + ANSI.cursorDown(1));
+        }
+        stdout.write(ANSI.cursorUp(renderedLines));
+        stdout.write(`${ANSI.green}✔${ANSI.reset} ${ANSI.bold}${prompt}${ANSI.reset} ${ANSI.cyan}${resultVals.length} selected${ANSI.reset}\n`);
+        return resultVals;
+      }
+
+      let redraw = false;
+      if (key === "\u001b[A" || key === "k") {
+        currentIdx = (currentIdx - 1 + options.length) % options.length;
+        redraw = true;
+      } else if (key === "\u001b[B" || key === "j") {
+        currentIdx = (currentIdx + 1) % options.length;
+        redraw = true;
+      } else if (key === " ") {
+        if (selections.has(currentIdx)) {
+          selections.delete(currentIdx);
+        } else {
+          selections.add(currentIdx);
+        }
+        redraw = true;
+      } else if (key === "a" || key === "A") {
+        options.forEach((_, idx) => selections.add(idx));
+        redraw = true;
+      } else if (key === "n" || key === "N") {
+        selections.clear();
+        redraw = true;
+      }
+
+      if (redraw) {
+        stdout.write(ANSI.cursorUp(renderedLines));
+        stdout.write(render());
+      }
+    }
+  } finally {
+    stdout.write(ANSI.showCursor);
+  }
+}
+
+/**
+ * Text input prompt with validation.
+ * @param {string} prompt
+ * @param {object} [opts]
+ * @returns {Promise<string>}
+ */
+export async function input(prompt, opts = {}) {
+  const stdin = opts.stdin || process.stdin;
+  const stdout = opts.stdout || process.stdout;
+  const defaultValue = opts.defaultValue ?? "";
+  const validate = opts.validate || (() => true);
+
+  if (!isTTY(stdin)) {
+    if (opts.fallbackValue !== undefined) {
+      return opts.fallbackValue;
+    }
+    stdout.write(`[Headless Input] ${prompt}: Auto-selected default [${defaultValue}]\n`);
+    return defaultValue;
+  }
+
+  const rl = createInterface({ input: stdin, output: stdout });
+
+  try {
+    while (true) {
+      const defaultHint = defaultValue ? ` ${ANSI.dim}(${defaultValue})${ANSI.reset}` : "";
+      const query = `${ANSI.bold}${ANSI.cyan}?${ANSI.reset} ${ANSI.bold}${prompt}${defaultHint}: `;
+      const rawAns = await rl.question(query);
+      const ans = rawAns.trim() || defaultValue;
+
+      const validRes = await validate(ans);
+      if (validRes === true) {
+        return ans;
+      }
+
+      const errMsg = typeof validRes === "string" ? validRes : "Invalid input";
+      stdout.write(`${ANSI.red}✖ ${errMsg}${ANSI.reset}\n`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Confirmation prompt (Y/n).
+ * @param {string} prompt
+ * @param {boolean} [defaultVal=true]
+ * @param {object} [opts]
+ * @returns {Promise<boolean>}
+ */
+export async function confirm(prompt, defaultVal = true, opts = {}) {
+  const stdin = opts.stdin || process.stdin;
+  const stdout = opts.stdout || process.stdout;
+
+  if (!isTTY(stdin)) {
+    const val = opts.fallbackValue ?? defaultVal;
+    stdout.write(`[Headless Confirm] ${prompt}: Auto-selected [${val ? "Yes" : "No"}]\n`);
+    return val;
+  }
+
+  const hint = defaultVal ? "[Y/n]" : "[y/N]";
+  const ans = await input(`${prompt} ${ANSI.dim}${hint}${ANSI.reset}`, {
+    defaultValue: defaultVal ? "y" : "n",
+    stdin,
+    stdout,
+  });
+
+  return /^y(es)?$/i.test(ans.trim());
+}
+
+/**
+ * Password / secret input prompt.
+ * @param {string} prompt
+ * @param {object} [opts]
+ * @returns {Promise<string>}
+ */
+export async function secretInput(prompt, opts = {}) {
+  const stdin = opts.stdin || process.stdin;
+  const stdout = opts.stdout || process.stdout;
+
+  if (!isTTY(stdin)) {
+    return opts.fallbackValue || "";
+  }
+
+  stdout.write(`${ANSI.bold}${ANSI.cyan}?${ANSI.reset} ${ANSI.bold}${prompt}:${ANSI.reset} `);
+  stdout.write(ANSI.hideCursor);
+
+  let inputStr = "";
+  try {
+    for await (const key of readKeypresses(stdin)) {
+      if (key === "\r" || key === "\n") {
+        stdout.write("\n");
+        return inputStr;
+      }
+      if (key === "\u007f" || key === "\b") {
+        // Backspace
+        if (inputStr.length > 0) {
+          inputStr = inputStr.slice(0, -1);
+          stdout.write("\b \b");
+        }
+      } else if (key.length === 1 && key >= " ") {
+        inputStr += key;
+        stdout.write("*");
+      }
+    }
+  } finally {
+    stdout.write(ANSI.showCursor);
+  }
+  return inputStr;
+}
+
+/**
+ * Terminal activity spinner indicator.
+ * @param {string} label
+ * @param {object} [opts]
+ * @returns {{ stop: (msg?: string) => void, fail: (msg?: string) => void }}
+ */
+export function spinner(label, opts = {}) {
+  const stdout = opts.stdout || process.stdout;
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  let frameIdx = 0;
+  let timer = null;
+
+  if (isTTY(stdout)) {
+    stdout.write(ANSI.hideCursor);
+    stdout.write(`${ANSI.cyan}${frames[0]}${ANSI.reset} ${label}`);
+
+    timer = setInterval(() => {
+      frameIdx = (frameIdx + 1) % frames.length;
+      stdout.write(ANSI.clearLine);
+      stdout.write(`${ANSI.cyan}${frames[frameIdx]}${ANSI.reset} ${label}`);
+    }, 80);
+  } else {
+    stdout.write(`[Starting] ${label}...\n`);
+  }
+
+  return {
+    stop(successMsg = `${label} complete`) {
+      if (timer) clearInterval(timer);
+      if (isTTY(stdout)) {
+        stdout.write(ANSI.clearLine);
+        stdout.write(`${ANSI.green}✔${ANSI.reset} ${successMsg}\n`);
+        stdout.write(ANSI.showCursor);
+      } else {
+        stdout.write(`[Completed] ${successMsg}\n`);
+      }
+    },
+    fail(errorMsg = `${label} failed`) {
+      if (timer) clearInterval(timer);
+      if (isTTY(stdout)) {
+        stdout.write(ANSI.clearLine);
+        stdout.write(`${ANSI.red}✖${ANSI.reset} ${errorMsg}\n`);
+        stdout.write(ANSI.showCursor);
+      } else {
+        stdout.write(`[Failed] ${errorMsg}\n`);
+      }
+    },
+  };
+}

package/src/wizard-init.mjs

@@ -0,0 +1,243 @@
+import { existsSync, readFileSync, writeFileSync, 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";
+
+export const TIER_PROFILES = {
+  free: {
+    concurrency: 1,
+    daily_tasks: 30,
+    stagger_ms: 3000,
+    diff_kb: 50,
+  },
+  pro: {
+    concurrency: 3,
+    daily_tasks: 300,
+    stagger_ms: 1500,
+    diff_kb: 75,
+  },
+  enterprise: {
+    concurrency: 10,
+    daily_tasks: 1000,
+    stagger_ms: 500,
+    diff_kb: 100,
+  },
+};
+
+export const BUILTIN_PRESETS = [
+  {
+    id: "nightly-security-audit",
+    title: "Nightly Security & Vulnerability Audit",
+    description: "Scans codebase for hardcoded secrets, TODO annotations, and outdated dependencies.",
+    cron: "0 2 * * *",
+  },
+  {
+    id: "flaky-test-quarantine",
+    title: "Statistical Flaky Test Quarantine",
+    description: "Monitors test execution stability via Wilson score interval and isolates flaky tests.",
+    cron: "*/30 * * * *",
+  },
+  {
+    id: "multi-agent-refactor-swarm",
+    title: "Multi-Agent Parallel Refactor Swarm",
+    description: "Splits refactoring tasks across isolated workspace file boundaries.",
+    cron: "manual",
+  },
+  {
+    id: "doc-sync-sentinel",
+    title: "AGENTS.md & API Doc Sync Sentinel",
+    description: "Validates documentation integrity against actual exported symbol signatures.",
+    cron: "0 9 * * 1",
+  },
+];
+
+/**
+ * Generate a deterministic onboarding plan for repository configuration.
+ * @param {string} [root=process.cwd()]
+ * @param {object} [options]
+ * @returns {{
+ *   stack: string,
+ *   tier: string,
+ *   verify: { test: string, build: string, lint: string, typecheck: string },
+ *   limits: { concurrency: number, daily_tasks: number, stagger_ms: number, diff_kb: number },
+ *   presets: Array<string>,
+ *   configYaml: string,
+ *   julesYaml: string
+ * }}
+ */
+export function planInit(root = process.cwd(), options = {}) {
+  const oracle = detectStackOracles(root);
+  const tierName = options.tier || "pro";
+  const limits = TIER_PROFILES[tierName] || TIER_PROFILES.pro;
+
+  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 || "",
+  };
+
+  const selectedPresets = options.presets || ["nightly-security-audit", "flaky-test-quarantine"];
+
+  const configYaml = `# Google Jules Orchestrator Kit Config (v0.29.0)
+version: 1
+provider: jules
+tier: ${tierName}
+base_branch: ${options.baseBranch || "main"}
+branch_prefix: agent/
+
+limits:
+  concurrency: ${limits.concurrency}
+  daily_tasks: ${limits.daily_tasks}
+  stagger_ms: ${limits.stagger_ms}
+  diff_kb: ${limits.diff_kb}
+
+verify:
+  test: "${verify.test}"
+  build: "${verify.build}"
+  lint: "${verify.lint}"
+  typecheck: "${verify.typecheck}"
+
+presets:
+${selectedPresets.map((p) => `  - ${p}`).join("\n")}
+`;
+
+  const julesYaml = `# Google Jules Agent Compatibility Manifest
+version: 1
+test_cmd: "${verify.test}"
+build_cmd: "${verify.build}"
+`;
+
+  return {
+    stack: oracle.stack,
+    tier: tierName,
+    verify,
+    limits,
+    presets: selectedPresets,
+    configYaml,
+    julesYaml,
+  };
+}
+
+/**
+ * Load declarative presets from .agent/presets/*.yml or fallback to built-ins.
+ * @param {string} [root=process.cwd()]
+ * @returns {Array<{ id: string, title: string, description: string, cron: string }>}
+ */
+export function loadPresets(root = process.cwd()) {
+  const presetsDir = join(root, ".agent", "presets");
+  const presets = [...BUILTIN_PRESETS];
+
+  if (existsSync(presetsDir)) {
+    try {
+      const files = readdirSync(presetsDir).filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"));
+      files.forEach((f) => {
+        try {
+          const content = readFileSync(join(presetsDir, f), "utf-8");
+          const parsed = parseYaml(content);
+          if (parsed && parsed.id && parsed.title) {
+            presets.push({
+              id: parsed.id,
+              title: parsed.title,
+              description: parsed.description || "",
+              cron: parsed.cron || "manual",
+            });
+          }
+        } catch (_) {}
+      });
+    } catch (_) {}
+  }
+
+  return presets;
+}
+
+/**
+ * Run interactive or headless onboarding wizard.
+ * @param {string} [root=process.cwd()]
+ * @param {object} [options]
+ * @returns {Promise<{ ok: boolean, configPath: string, plan: object }>}
+ */
+export async function runInitWizard(root = process.cwd(), options = {}) {
+  const interactive = options.interactive !== false && isTTY(options.stdin || process.stdin);
+
+  let selectedTier = options.tier || "pro";
+  let testCmd = options.testCmd;
+  let buildCmd = options.buildCmd;
+  let selectedPresets = options.presets;
+
+  if (interactive) {
+    const oracle = detectStackOracles(root);
+    const sp = spinner("Inspecting repository stack and verification oracles", options);
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    sp.stop(`Detected Stack: ${oracle.stack}`);
+
+    selectedTier = await select(
+      [
+        { label: "Pro Tier (Recommended)", value: "pro", description: "3 parallel workers, 300 daily tasks, 75 KB diff limit" },
+        { label: "Free / Individual Tier", value: "free", description: "1 worker, 30 daily tasks, 50 KB diff limit" },
+        { label: "Custom Enterprise", value: "enterprise", description: "10 workers, 1000 daily tasks, 100 KB diff limit" },
+      ],
+      "Select Jules Orchestrator Usage Tier",
+      options
+    );
+
+    testCmd = await input("Verification Test Command", {
+      defaultValue: oracle.candidates.testCmd || "npm test",
+      stdin: options.stdin,
+      stdout: options.stdout,
+    });
+
+    buildCmd = await input("Verification Build Command", {
+      defaultValue: oracle.candidates.buildCmd || "",
+      stdin: options.stdin,
+      stdout: options.stdout,
+    });
+
+    const presetOptions = BUILTIN_PRESETS.map((p) => ({
+      label: p.title,
+      value: p.id,
+      checked: true,
+      description: p.description,
+    }));
+
+    selectedPresets = await multiSelect(presetOptions, "Select Autonomous Workflows to Enable", options);
+
+    const shouldProbe = await confirm("Run verification probe on test command before saving?", true, options);
+    if (shouldProbe && testCmd) {
+      const probeSp = spinner(`Probing oracle: ${testCmd}`, options);
+      const probeRes = await runVerificationProbe(testCmd, root);
+      if (probeRes.ok) {
+        probeSp.stop(`Oracle verified successfully (${probeRes.durationMs}ms)`);
+      } else {
+        probeSp.fail(`Oracle verification probe failed (Exit ${probeRes.code})`);
+      }
+    }
+  }
+
+  const plan = planInit(root, {
+    tier: selectedTier,
+    testCmd,
+    buildCmd,
+    presets: selectedPresets,
+    ...options,
+  });
+
+  // Atomic write plan
+  const agentDir = join(root, ".agent");
+  if (!existsSync(agentDir)) {
+    mkdirSync(agentDir, { recursive: true });
+  }
+
+  const configPath = join(agentDir, "config.yml");
+  const julesPath = join(agentDir, "jules.yml");
+
+  writeFileSync(configPath, plan.configYaml, "utf-8");
+  writeFileSync(julesPath, plan.julesYaml, "utf-8");
+
+  return {
+    ok: true,
+    configPath,
+    plan,
+  };
+}

package/src/wizard-oracle.mjs

@@ -0,0 +1,155 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { detectStack, parseYaml } from "./config.mjs";
+import { runCmd } from "./git.mjs";
+
+/**
+ * Inspect repository topology, workspace structure, and manifests to infer candidate verification oracles.
+ * @param {string} [root=process.cwd()]
+ * @returns {{
+ *   stack: string,
+ *   isMonorepo: boolean,
+ *   packages: Array<{ path: string, name: string, stack: string }>,
+ *   candidates: {
+ *     testCmd: string,
+ *     buildCmd: string,
+ *     lintCmd: string,
+ *     typecheckCmd: string
+ *   }
+ * }}
+ */
+export function detectStackOracles(root = process.cwd()) {
+  const detected = detectStack(root);
+  const stack = detected.stack || "node";
+
+  const candidates = {
+    testCmd: detected.testCmd || "",
+    buildCmd: detected.buildCmd || "",
+    lintCmd: "",
+    typecheckCmd: "",
+  };
+
+  const isMonorepo =
+    existsSync(join(root, "turbo.json")) ||
+    existsSync(join(root, "pnpm-workspace.yaml")) ||
+    existsSync(join(root, "lerna.json")) ||
+    existsSync(join(root, "nx.json"));
+
+  const packages = [];
+
+  // Check Node.json package.json scripts
+  const pkgPath = join(root, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      const scripts = pkg.scripts || {};
+
+      if (scripts.test) candidates.testCmd = candidates.testCmd || "npm test";
+      if (scripts.build) candidates.buildCmd = candidates.buildCmd || "npm run build";
+      if (scripts.lint) candidates.lintCmd = "npm run lint";
+      if (scripts.typecheck || scripts["type-check"]) {
+        candidates.typecheckCmd = scripts.typecheck ? "npm run typecheck" : "npm run type-check";
+      } else if (existsSync(join(root, "tsconfig.json"))) {
+        candidates.typecheckCmd = "npx tsc --noEmit";
+      }
+    } catch (_) {}
+  }
+
+  // Check Cargo workspace
+  if (stack.includes("cargo") || existsSync(join(root, "Cargo.toml"))) {
+    const isCargoWs = existsSync(join(root, "Cargo.toml")) && readFileSync(join(root, "Cargo.toml"), "utf-8").includes("[workspace]");
+    const flag = isCargoWs ? " --workspace" : "";
+    candidates.testCmd = `cargo test${flag}`;
+    candidates.buildCmd = `cargo build${flag}`;
+    candidates.lintCmd = `cargo clippy${flag} -- -D warnings`;
+    candidates.typecheckCmd = `cargo check${flag}`;
+  }
+
+  // Check Go module
+  if (stack.includes("go") || existsSync(join(root, "go.mod"))) {
+    candidates.testCmd = candidates.testCmd || "go test ./...";
+    candidates.buildCmd = candidates.buildCmd || "go build ./...";
+    candidates.lintCmd = candidates.lintCmd || "golangci-lint run";
+    candidates.typecheckCmd = candidates.typecheckCmd || "go vet ./...";
+  }
+
+  // Check Python
+  if (stack.includes("pytest") || existsSync(join(root, "pyproject.toml")) || existsSync(join(root, "requirements.txt"))) {
+    candidates.testCmd = candidates.testCmd || "pytest";
+    candidates.buildCmd = candidates.buildCmd || "";
+    candidates.lintCmd = candidates.lintCmd || "flake8 .";
+    candidates.typecheckCmd = candidates.typecheckCmd || "mypy .";
+  }
+
+  // Discover subpackages if monorepo
+  if (isMonorepo) {
+    if (existsSync(join(root, "pnpm-workspace.yaml"))) {
+      try {
+        const parsed = parseYaml(readFileSync(join(root, "pnpm-workspace.yaml"), "utf-8"));
+        const globs = parsed?.packages || ["packages/*"];
+        globs.forEach((pattern) => {
+          const dirBase = pattern.replace(/\/\*$/, "");
+          const fullDir = join(root, dirBase);
+          if (existsSync(fullDir)) {
+            const children = readdirSync(fullDir);
+            children.forEach((child) => {
+              const childPath = join(fullDir, child);
+              if (existsSync(join(childPath, "package.json"))) {
+                packages.push({
+                  path: join(dirBase, child),
+                  name: child,
+                  stack: "node",
+                });
+              }
+            });
+          }
+        });
+      } catch (_) {}
+    }
+  }
+
+  return {
+    stack,
+    isMonorepo,
+    packages,
+    candidates,
+  };
+}
+
+/**
+ * Execute a candidate verification command to prove oracle validity.
+ * @param {string} cmd
+ * @param {string} [cwd=process.cwd()]
+ * @param {object} [options]
+ * @returns {Promise<{ ok: boolean, code: number, stdout: string, stderr: string, durationMs: number }>}
+ */
+export async function runVerificationProbe(cmd, cwd = process.cwd(), options = {}) {
+  const start = Date.now();
+  const timeoutMs = options.timeoutMs || 30_000;
+
+  if (!cmd || !cmd.trim()) {
+    return { ok: true, code: 0, stdout: "", stderr: "Empty oracle command (skipped)", durationMs: 0 };
+  }
+
+  try {
+    const res = runCmd(cmd, { cwd, timeout: timeoutMs });
+    const durationMs = Date.now() - start;
+    const ok = res.status === 0;
+    return {
+      ok,
+      code: res.status ?? (ok ? 0 : 1),
+      stdout: res.stdout || "",
+      stderr: res.stderr || "",
+      durationMs,
+    };
+  } catch (err) {
+    const durationMs = Date.now() - start;
+    return {
+      ok: false,
+      code: 1,
+      stdout: "",
+      stderr: err.message,
+      durationMs,
+    };
+  }
+}

package/src/wizard-task.mjs

@@ -0,0 +1,193 @@
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig } from "./config.mjs";
+import { gate } from "./engine.mjs";
+import { scanDiff, shannonEntropy } from "./security.mjs";
+import { scanCodebaseForTodos } from "../scripts/jules-scan-todos.mjs";
+import { select, input, confirm, spinner, isTTY } from "./tui.mjs";
+
+export const GUARDRAIL_FOOTER = `
+---
+HARD CONSTRAINTS:
+- Do NOT modify package.json, pnpm-lock.yaml, tsconfig.json, or .github/ files.
+- Diff Payload Governor: Keep total diff payload under 75 KB (\`git diff | wc -c\`).
+- Falsifiable & Evidence-Based: Attach full terminal verification output to PR. Never weaken assertions or delete failing tests to force a pass.
+- Read-Before-Write: Inspect existing symbol signatures, definitions, and call sites before making edits.
+- BEFORE opening the PR: Run \`git fetch origin main && git rebase origin/main\`, then re-verify.
+`;
+
+/**
+ * Pure planning core for task creation & envelope synthesis.
+ * @param {string} root
+ * @param {object} inputObj
+ * @returns {{
+ *   ok: boolean,
+ *   taskId: string,
+ *   title: string,
+ *   prompt: string,
+ *   fullPrompt: string,
+ *   verifyCmd: string,
+ *   flags: { autoPr: boolean, requirePlanApproval: boolean, repoless: boolean, startingBranch: string },
+ *   secretFindings: Array<any>,
+ *   gateResult: object,
+ *   taskFileContent: string
+ * }}
+ */
+export function planTaskCreate(root = process.cwd(), inputObj = {}) {
+  const config = loadConfig(root);
+
+  const title = inputObj.title || "Agent Task";
+  const rawPrompt = inputObj.prompt || "";
+  const verifyCmd = inputObj.verifyCmd || config.verify.test || config.verify.build || "";
+
+  // 1. Falsifiability check
+  if (!rawPrompt.trim()) {
+    throw new Error("Task prompt cannot be empty.");
+  }
+  if (!verifyCmd && !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."
+    );
+  }
+
+  // 2. Secret Scrubbing Preflight
+  const secretFindings = [];
+  const secretScan = scanDiff(`+${rawPrompt}`);
+  if (!secretScan.ok) {
+    secretScan.findings.forEach((f) => secretFindings.push(f));
+  }
+  if (shannonEntropy(rawPrompt) > 4.5 && !inputObj.allowHighEntropy) {
+    secretFindings.push({ id: "HIGH_ENTROPY_PROMPT", line: 1 });
+  }
+
+  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.`
+    );
+  }
+
+  // 3. Jules v1alpha Flags
+  const flags = {
+    autoPr: Boolean(inputObj.autoPr),
+    requirePlanApproval: Boolean(inputObj.requirePlanApproval),
+    repoless: Boolean(inputObj.repoless),
+    startingBranch: inputObj.startingBranch || config.baseBranch || "main",
+  };
+
+  // 4. Prompt Envelope & Guardrail Footer Synthesis
+  const fullPrompt = `[TASK INSTRUCTIONS]
+${rawPrompt}
+
+[VERIFICATION ORACLE]
+Test/Verification Command: ${verifyCmd || "(None)"}
+
+${GUARDRAIL_FOOTER}`;
+
+  const taskId = inputObj.id || `TASK-${Date.now().toString(36).toUpperCase()}`;
+
+  const taskFileContent = `# ${title}
+# Task ID: ${taskId}
+# Auto-PR: ${flags.autoPr} | Plan Approval: ${flags.requirePlanApproval} | Repoless: ${flags.repoless}
+
+${fullPrompt}
+`;
+
+  return {
+    ok: true,
+    taskId,
+    title,
+    prompt: rawPrompt,
+    fullPrompt,
+    verifyCmd,
+    flags,
+    secretFindings,
+    taskFileContent,
+  };
+}
+
+/**
+ * Run interactive or headless task creation wizard.
+ * @param {string} [root=process.cwd()]
+ * @param {object} [options]
+ * @returns {Promise<{ ok: boolean, taskFile: string, plan: object }>}
+ */
+export async function runTaskCreateWizard(root = process.cwd(), options = {}) {
+  const interactive = options.interactive !== false && isTTY(options.stdin || process.stdin);
+
+  let title = options.title;
+  let promptText = options.prompt;
+  let verifyCmd = options.verifyCmd;
+  let autoPr = options.autoPr;
+  let requirePlanApproval = options.requirePlanApproval;
+  let repoless = options.repoless;
+
+  if (interactive) {
+    const sp = spinner("Analyzing codebase task candidates & gate policy", options);
+    const todos = scanCodebaseForTodos(root);
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    sp.stop(`Scanned ${todos.length} TODO/FIXME candidates`);
+
+    if (todos.length > 0 && !promptText) {
+      const useTodo = await confirm("Import prompt from scanned TODO candidate?", false, options);
+      if (useTodo) {
+        const selectedTodo = await select(
+          todos.slice(0, 10).map((t) => ({
+            label: `[${t.type}] ${t.text} (${t.file}:${t.line})`,
+            value: t,
+          })),
+          "Select TODO Candidate",
+          options
+        );
+        title = `Fix ${selectedTodo.type}: ${selectedTodo.text.slice(0, 40)}`;
+        promptText = `Resolve ${selectedTodo.type} in ${selectedTodo.file} at line ${selectedTodo.line}: ${selectedTodo.text}`;
+      }
+    }
+
+    title = await input("Task Title", {
+      defaultValue: title || "Refactor Component Module",
+      stdin: options.stdin,
+      stdout: options.stdout,
+    });
+
+    promptText = await input("Detailed Task Instructions", {
+      defaultValue: promptText || "Cleanly refactor module to improve readability and maintain full test coverage.",
+      stdin: options.stdin,
+      stdout: options.stdout,
+    });
+
+    autoPr = await confirm("Enable Automatic PR Creation (automationMode: AUTO_CREATE_PR)?", true, options);
+    requirePlanApproval = await confirm("Require Plan Approval Gate before execution?", false, options);
+    repoless = await confirm("Dispatch in Repoless mode (no repo source context)?", false, options);
+  }
+
+  const plan = planTaskCreate(root, {
+    title,
+    prompt: promptText,
+    verifyCmd,
+    autoPr,
+    requirePlanApproval,
+    repoless,
+    ...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}).`);
+  }
+
+  // Write Task File to .agent/queue/
+  const queueDir = join(root, ".agent", "queue");
+  if (!existsSync(queueDir)) {
+    mkdirSync(queueDir, { recursive: true });
+  }
+
+  const taskFile = join(queueDir, `${plan.taskId}.md`);
+  writeFileSync(taskFile, plan.taskFileContent, "utf-8");
+
+  return {
+    ok: true,
+    taskFile,
+    plan,
+  };
+}