jules-orchestrator-kit 0.74.0 → 0.75.1

package/bin/agentctl.mjs

@@ -5,10 +5,11 @@ import { readFileSync, existsSync, readdirSync, statSync, renameSync, mkdirSync
 import { join, resolve, relative } from "node:path";
 import { applyEnvAliases } from "../src/env-aliases.mjs";
 import { selectFailureOutput } from "../src/ops/verify-output.mjs";
+import { diagnoseVerifyFailure } from "../src/ops/toolchain-diagnostics.mjs";
 import { loadConfig, resolveRoot, detectStack, bootstrapZeroTestRepo } from "../src/config.mjs";
 import { gate, dispatch, run, isTaskFile } from "../src/engine.mjs";
-import { acquireLock, releaseLock, lockStatus, getQueueDir } from "../src/state.mjs";
-import { parseEnvelopeHeader } from "../src/envelope.mjs";
+import { acquireLock, releaseLock, reapStaleLocks, lockStatus, getQueueDir } from "../src/state.mjs";
+import { parseEnvelopeHeader, validateEnvelope } from "../src/envelope.mjs";
 import { worktreePrune } from "../src/git.mjs";
 import { reapOrphanedIntents, reapStaleMutexDirs } from "../src/journal.mjs";
 import { KIT_VERSION } from "../src/version.mjs";
@@ -89,7 +90,8 @@ export function printHelp() {
   lines.push("  --prompt-file, -f     Read the prompt from a file (-f is --fix on task optimize)");
   lines.push("  --role, -r            Specify specialist agent role (auditor | performance | security | hygiene | resilience | types | debugger | testing | e2e | database | docs | a11y)");
   lines.push("  --tier                Force routing tier when router.enabled (fast | complex) — see .agent/config.yml router:");
-  lines.push("  --check-premise       Verify task goal/oracle passes locally before burning API budget");
+  lines.push("  --check-premise       Skip only when an explicit --goal-check proves the task complete");
+  lines.push("  --goal-check <cmd>    Objective-specific command; distinct from --verify-cmd");
   lines.push("  --dag                 Execute queue tasks via DAG dependency resolution");
   lines.push("  --dry-run, -d         Simulate action without making API calls or modifying git");
   lines.push("  --mode, -m            Gate evaluation mode (working-tree | committed | staged)");
@@ -268,6 +270,11 @@ async function main() {
   // tool; a newcomer cannot tell which entry is step one, and guessing wrong
   // costs them a confusing failure instead of a hint.
   if (!command) {
+    if (args.includes("-i") || args.includes("--interactive")) {
+      const { runTuiMenu } = await import("../src/ops/tui-menu.mjs");
+      await runTuiMenu(resolveRoot());
+      process.exit(0);
+    }
     const { resolveNextStep, renderNextStep } = await import("../src/ops/next-step.mjs");
     const cwd = process.cwd();
     let budgetLine = "";
@@ -308,9 +315,14 @@ async function main() {
   // Init is a configuration boundary, not an operational maintenance command.
   // In particular, --dry-run must not create .agent/ indirectly by reaping
   // journal intents or mutex directories before init itself gets control.
-  if (command !== "init") {
+  // init, uninstall and migrate must not create kit state as a side-effect of
+  // startup maintenance — dry-run and "nothing installed" paths need a clean tree.
+  if (command !== "init" && command !== "uninstall" && command !== "migrate") {
     reapOrphanedIntents(root);
     reapStaleMutexDirs(root);
+    if (command !== "lock") {
+      reapStaleLocks(root);
+    }
   }
   const config = loadConfig(root);
 
@@ -331,7 +343,9 @@ async function main() {
           "require-plan-approval": { type: "boolean" },
           "auto-approve-plans": { type: "boolean" },
           "auto-approve": { type: "boolean" },
+          "auto-reply": { type: "boolean" },
           "check-premise": { type: "boolean" },
+          "goal-check": { type: "string" },
           idempotent: { type: "boolean" },
           author: { type: "string" },
           "verify-cmd": { type: "string", short: "v" },
@@ -383,6 +397,7 @@ async function main() {
       }
 
       const autoApprove = Boolean(values["auto-approve-plans"] || values["auto-approve"]);
+      const autoReply = Boolean(values["auto-reply"] || values.autoReply);
       const task = {
         title: values.title || "CLI Dispatch Task",
         prompt: promptContent,
@@ -393,7 +408,10 @@ async function main() {
         repoless: values.repoless,
         autoPr: values["auto-pr"],
         requirePlanApproval: autoApprove ? false : values["require-plan-approval"],
+        autoApprovePlan: autoApprove,
+        autoReply,
         checkPremise: values["check-premise"] || values.idempotent,
+        goalCheck: values["goal-check"],
         author: values.author,
         verifyCmd: values["verify-cmd"] || values.verify,
       };
@@ -407,13 +425,15 @@ async function main() {
           source: values.source,
           branch: values.branch,
           checkPremise: values["check-premise"] || values.idempotent,
+          autoApprovePlan: autoApprove,
+          autoReply,
         });
         if (values.json) {
           console.log(JSON.stringify({ ok: true, session }, null, 2));
         } else {
           if (session.status === "ALREADY_SATISFIED" || session.skipped) {
             console.log(`\n⚡ Task Already Satisfied (skipped dispatch):`);
-            console.log(`   Reason: ${session.reason || "Verification oracle already passing on base branch."}`);
+            console.log(`   Reason: ${session.reason || "Explicit goal check passed on a clean revision."}`);
           } else if (values["dry-run"]) {
             // The dry run reached the provider adapter and stopped short of the
             // call. Printing the same "Dispatched Successfully!" banner as a
@@ -424,9 +444,16 @@ async function main() {
             console.log(`   Title       : ${task.title}`);
             console.log(`   Provider    : ${session.provider || config.provider || "jules"}`);
             if (task.role) console.log(`   Role        : ${task.role}`);
+            if (task.branch) console.log(`   Branch      : ${task.branch}`);
+            if (task.verifyCmd) console.log(`   Verify Cmd  : ${task.verifyCmd}`);
             if (session._routeTier) {
               console.log(`   Router Tier : ${session._routeTier} (${session._routeReason || "n/a"})`);
             }
+            if (task.prompt) {
+              console.log(`\n--- Task Payload Preview ---`);
+              console.log(String(task.prompt).trim());
+              console.log(`----------------------------`);
+            }
             console.log(`\n   Re-run without --dry-run to dispatch for real.`);
           } else {
             console.log(`\n✅ Task Dispatched Successfully!`);
@@ -690,9 +717,14 @@ async function main() {
             console.log(`   • Or set it by hand:   verify.test in ${config._file || ".agent/config.yml"}`);
             console.log(`   • Scope- and secret-scanning only, on purpose? Set verify.required: false there.\n`);
           } else if (failedPhase === "verify" || failedPhase === "evidence") {
+            const verifyFailure =
+              res.phases.find((p) => (p.phase === "verify" || p.phase === "evidence") && !p.ok)?.failure || {};
+            const diagnosis = diagnoseVerifyFailure(verifyFailure);
             console.log(`💡 Remediation Hint (Exit ${res.code} Verification Failed):`);
-            console.log(`   • The stage above exited non-zero. Reproduce it locally, then re-run the gate.`);
-            console.log(`   • To start an explicit repair workflow, pipe the failing command's output to: agentctl repair\n`);
+            for (const line of diagnosis.lines) {
+              console.log(`   • ${line}`);
+            }
+            console.log("");
           } else if (res.code === 3) {
             // The same violation has two very different causes. Right after
             // `init`, every offending path is a file the tool itself just wrote
@@ -992,6 +1024,8 @@ async function main() {
           cmd: { type: "string", short: "c" },
           task: { type: "boolean", short: "t" },
           author: { type: "string" },
+          "auto-approve": { type: "boolean" },
+          "auto-reply": { type: "boolean" },
           json: { type: "boolean", short: "j" },
           "dry-run": { type: "boolean" },
         },
@@ -1038,17 +1072,59 @@ async function main() {
         }
         process.exit(0);
       } else {
-        console.log(`\n🔧 Dispatching OODA Repair Loop for captured failure trace...`);
+        if (!values.json) {
+          console.log(`\n🔧 Dispatching OODA Repair Loop for captured failure trace...`);
+        }
         const repairRes = await repair(
           { stderr: cleanTrace, command: values.cmd || "verify" },
-          { root, dryRun: values["dry-run"], author: values.author }
+          {
+            root,
+            dryRun: values["dry-run"],
+            author: values.author,
+            autoApprove: values["auto-approve"],
+            autoReply: values["auto-reply"],
+          }
         );
 
         if (values.json) {
-          console.log(JSON.stringify(repairRes, null, 2));
+          process.stdout.write(JSON.stringify(repairRes, null, 2) + "\n", () => {
+            process.exit(repairRes.ok ? 0 : 1);
+          });
+          setTimeout(() => process.exit(repairRes.ok ? 0 : 1), 1000).unref();
+          break;
         } else {
           console.log(`------------------------------------------------------------------`);
           console.log(`Repair Status: ${repairRes.ok ? "RESOLVED (Exit 0)" : `FAILED (${repairRes.finalStatus} — Exit 1)`}`);
+          if (!repairRes.ok && Array.isArray(repairRes.attempts) && repairRes.attempts.length > 0) {
+            console.log(`\nRepair attempt review:`);
+            if (repairRes.repairDir) {
+              console.log(`  Retained under: ${repairRes.repairDir}`);
+            }
+            for (const attempt of repairRes.attempts) {
+              const phase =
+                attempt.phase ||
+                attempt.diagnostics?.phase ||
+                (attempt.verified === true ? "verified" : attempt.verified === false ? "verify" : "unknown");
+              const errRaw = attempt.error || attempt.diagnostics?.error || "";
+              const concise = String(errRaw).split("\n")[0].slice(0, 200);
+              const diff = typeof attempt.diff === "string" ? attempt.diff : "";
+              const fileCount = [...diff.matchAll(/^diff --git /gm)].length;
+              const lineCount = diff
+                .split("\n")
+                .filter((line) => (line.startsWith("+") && !line.startsWith("+++")) || (line.startsWith("-") && !line.startsWith("---")))
+                .length;
+              console.log(`  #${attempt.n}: phase=${phase} ok=${attempt.ok}${concise ? ` error=${JSON.stringify(concise)}` : ""}`);
+              if (attempt.diff !== undefined) {
+                console.log(`       diff: ${fileCount} file(s), ${lineCount} changed line(s)`);
+              }
+              if (attempt.diagnostics?.patchPath) {
+                console.log(`       patch: ${attempt.diagnostics.patchPath}`);
+              }
+              if (attempt.diagnostics?.diagnosticsPath) {
+                console.log(`       diagnostics: ${attempt.diagnostics.diagnosticsPath}`);
+              }
+            }
+          }
         }
 
         process.exit(repairRes.ok ? 0 : 1);
@@ -1517,6 +1593,7 @@ async function main() {
         options: {
           ttl: { type: "string" },
           pid: { type: "string" },
+          "dry-run": { type: "boolean", short: "d" },
           json: { type: "boolean", short: "j" },
         },
         allowPositionals: true,
@@ -1581,22 +1658,49 @@ async function main() {
           console.log(`❌ Lock for ${taskId} not found or release failed`);
           process.exit(1);
         }
+      } else if (action === "reap" || action === "prune") {
+        const dryRun = Boolean(lockValues["dry-run"]);
+        const res = reapStaleLocks(root, { dryRun });
+        if (lockValues.json) {
+          console.log(JSON.stringify(res, null, 2));
+          process.exit(0);
+        }
+        if (res.reapedCount === 0) {
+          console.log("✅ No stale locks found.");
+        } else {
+          const verb = dryRun ? "Would reap" : "Reaped";
+          console.log(`✅ ${verb} ${res.reapedCount} stale lock(s):`);
+          for (const item of res.reaped) {
+            console.log(`   • ${item.taskId || item.file} (${item.reason})`);
+          }
+        }
+        process.exit(0);
       } else {
-        const locks = lockStatus(root);
+        const allLocks = lockStatus(root);
+        const activeLocks = allLocks.filter((l) => l.live);
+        const staleLocks = allLocks.filter((l) => !l.live);
         if (lockValues.json) {
-          console.log(JSON.stringify({ ok: true, locks }, null, 2));
+          console.log(JSON.stringify({ ok: true, locks: allLocks, activeCount: activeLocks.length, staleCount: staleLocks.length }, null, 2));
           process.exit(0);
         }
-        if (locks.length === 0) {
+        if (allLocks.length === 0) {
           console.log("Active Locks: 0 (no held locks)");
         } else {
-          console.log(`Active Locks (${locks.length}):`);
-          for (const l of locks) {
+          console.log(`Active Locks (${activeLocks.length}):`);
+          for (const l of activeLocks) {
             const files = Array.isArray(l.files) ? l.files.join(", ") : (l.files || "");
             const expires = l.expiresAt ? `expires ${l.expiresAt}` : (l.ownerPid ? `pid ${l.ownerPid}` : "active");
             console.log(`  • taskId: ${l.taskId || l.id} [${l.agent || "unknown"}] (${expires})`);
             if (files) console.log(`    Paths: ${files}`);
           }
+          if (staleLocks.length > 0) {
+            console.log(`\nStale Locks (${staleLocks.length}):`);
+            for (const l of staleLocks) {
+              const reason = l.leased ? "expired lease" : `dead pid ${l.pid || "unknown"}`;
+              console.log(`  • taskId: ${l.taskId || l.id} [${l.agent || "unknown"}] (${reason})`);
+            }
+            console.log(`   💡 Run \`agentctl lock reap\` to clean up stale locks.`);
+          }
         }
       }
       process.exit(0);
@@ -1791,7 +1895,7 @@ async function main() {
     case "ci": {
       const sub = args[1];
       if (sub !== "init") {
-        console.error(`❌ Unknown 'ci' action '${sub || ""}'. Usage: agentctl ci init [--target github|gitlab] [--force]`);
+        console.error(`❌ Unknown 'ci' action '${sub || ""}'. Usage: agentctl ci init [--target github|gitlab] [--force] [--with-automerge]`);
         process.exit(2);
       }
       const { values } = parseArgs({
@@ -1801,6 +1905,7 @@ async function main() {
           force: { type: "boolean", short: "f" },
           "dry-run": { type: "boolean", short: "d" },
           json: { type: "boolean", short: "j" },
+          "with-automerge": { type: "boolean" },
         },
         allowPositionals: true,
       });
@@ -1812,6 +1917,7 @@ async function main() {
         config,
         version: VERSION,
         stack: detectStack(root),
+        withAutomerge: values["with-automerge"],
       });
 
       if (values.json) {
@@ -1822,9 +1928,13 @@ async function main() {
         console.error(`❌ ${res.error}`);
         process.exit(1);
       }
-      console.log(`✅ ${res.written ? "Wrote" : "Would write"} ${res.file}`);
+      const filesDesc = Array.isArray(res.files) ? res.files.join(", ") : res.file;
+      console.log(`✅ ${res.written ? "Wrote" : "Would write"} ${filesDesc}`);
       console.log(`   Stack: ${res.stack} · runtime setup: ${res.setupSummary}`);
       console.log(`   The workflow runs: agentctl check --mode committed`);
+      if (values["with-automerge"]) {
+        console.log(`   Auto-merge: enabled for authorized agent pull requests via workflow_run`);
+      }
       if (!res.written && !values["dry-run"]) {
         console.log(`   (unchanged — pass --force to overwrite)`);
       }
@@ -1921,6 +2031,15 @@ async function main() {
       break;
     }
 
+    case "menu":
+    case "tui":
+    case "ui": {
+      const { runTuiMenu } = await import("../src/ops/tui-menu.mjs");
+      await runTuiMenu(root);
+      process.exit(0);
+      break;
+    }
+
     case "init": {
       const { values } = parseArgs({
         args: args.slice(1),
@@ -2099,6 +2218,7 @@ async function main() {
             yes: { type: "boolean", short: "y" },
             json: { type: "boolean", short: "j" },
             "dry-run": { type: "boolean", short: "d" },
+            "allow-protected": { type: "boolean" },
           },
           allowPositionals: true,
         });
@@ -2129,6 +2249,7 @@ async function main() {
           repoless: values.repoless,
           interactive: isInteractive,
           dryRun: values["dry-run"],
+          allowProtected: Boolean(values["allow-protected"]),
         });
 
         if (values.json) {
@@ -2255,8 +2376,87 @@ async function main() {
           console.log(`--------------------------------------------------\n`);
         }
         process.exit(analysis.isFalsifiable ? 0 : 1);
+      } else if (subCommand === "validate") {
+        const { values, positionals } = parseArgs({
+          args: args.slice(2),
+          options: {
+            json: { type: "boolean", short: "j" },
+          },
+          allowPositionals: true,
+        });
+
+        const target = positionals[0];
+        if (!target) {
+          console.error("Usage: agentctl task validate <path-to-envelope.md|json> [--json]");
+          process.exit(1);
+        }
+
+        const targetPath = resolve(root, target);
+        if (!existsSync(targetPath)) {
+          console.error(`Error: Envelope file not found: ${target}`);
+          process.exit(1);
+        }
+
+        let payload = null;
+        try {
+          const content = readFileSync(targetPath, "utf-8");
+          if (targetPath.endsWith(".json") || target.toLowerCase().endsWith(".json")) {
+            payload = JSON.parse(content);
+          } else {
+            payload = parseEnvelopeHeader(content);
+            if (!payload || typeof payload !== "object") {
+              try {
+                payload = JSON.parse(content);
+              } catch {
+                payload = null;
+              }
+            }
+          }
+        } catch (err) {
+          console.error(`Error: Failed to read or parse envelope: ${err.message}`);
+          process.exit(1);
+        }
+
+        if (!payload || typeof payload !== "object") {
+          console.error("❌ TASK ENVELOPE VALIDATION FAILED:");
+          console.error("  - File does not contain a valid JSON payload or task envelope frontmatter.");
+          process.exit(1);
+        }
+
+        const res = validateEnvelope(payload, { root });
+        const result = {
+          ok: res.ok === true,
+          file: target,
+          errors: Array.isArray(res.errors) ? res.errors : [],
+          warnings: Array.isArray(res.warnings) ? res.warnings : [],
+        };
+
+        if (values.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else if (!result.ok) {
+          console.error("❌ TASK ENVELOPE VALIDATION FAILED:");
+          for (const err of result.errors) {
+            console.error(`  - ${err}`);
+          }
+          if (result.warnings.length > 0) {
+            console.warn("⚠️ TASK ENVELOPE WARNINGS:");
+            for (const w of result.warnings) {
+              console.warn(`  - ${w}`);
+            }
+          }
+        } else {
+          if (result.warnings.length > 0) {
+            console.warn("⚠️ TASK ENVELOPE WARNINGS:");
+            for (const w of result.warnings) {
+              console.warn(`  - ${w}`);
+            }
+          }
+          console.log(`✅ Task envelope validated successfully: ${target}`);
+        }
+
+        process.exit(result.ok ? 0 : 1);
       } else {
-        console.error(`Unknown task subcommand '${subCommand}'. Supported: agentctl task create, agentctl task optimize, agentctl task template`);
+        console.error(`Unknown task subcommand '${subCommand}'. Supported: agentctl task create, agentctl task optimize, agentctl task template, agentctl task validate`);
         process.exit(1);
       }
       break;
@@ -2279,7 +2479,7 @@ async function main() {
           version: VERSION,
           root,
           pendingTasks: files.length,
-          activeLocks: lockStatus(root).length,
+          activeLocks: lockStatus(root, { activeOnly: true }).length,
           budget,
         }, null, 2));
         process.exit(0);
@@ -2288,7 +2488,7 @@ async function main() {
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Pending Tasks    : ${files.length}`);
-      console.log(`  Active VFS Locks : ${lockStatus(root).length}`);
+      console.log(`  Active VFS Locks : ${lockStatus(root, { activeOnly: true }).length}`);
       console.log(`  Daily Budget     : ${formatBudgetLine(budget)}`);
       console.log(`--------------------------------------------------\n`);
       process.exit(0);
@@ -3332,10 +3532,182 @@ async function main() {
       break;
     }
 
-    default:
-      console.error(`Unknown command: ${command}`);
-      printHelp();
+    case "migrate": {
+      const { values } = parseArgs({
+        args: args.slice(1),
+        options: {
+          "dry-run": { type: "boolean", short: "d" },
+          yes: { type: "boolean", short: "y" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+
+      const dryRun = Boolean(values["dry-run"]);
+      const confirmed = Boolean(values.yes);
+      const asJson = Boolean(values.json);
+
+      if (!dryRun && !confirmed) {
+        if (asJson) {
+          console.error(JSON.stringify({
+            ok: false,
+            error: "Refusing to migrate without --yes. Pass --dry-run to preview, or --yes to confirm.",
+          }));
+        } else {
+          console.error("❌ Refusing to migrate without --yes. Pass --dry-run to preview, or --yes to confirm.");
+        }
+        process.exit(1);
+      }
+
+      const { executeMigration } = await import("../src/migrate.mjs");
+      const res = executeMigration(root, { dryRun });
+
+      if (!res.ok) {
+        if (asJson) {
+          console.log(JSON.stringify(res, null, 2));
+        } else {
+          console.error(`❌ ${res.error || "Migration failed."}`);
+        }
+        process.exit(1);
+      }
+
+      if (asJson) {
+        const payload = {
+          ok: true,
+          dryRun: Boolean(res.dryRun),
+          migrated: res.migrated,
+          warnings: res.warnings || [],
+        };
+        if (res.message) payload.message = res.message;
+        console.log(JSON.stringify(payload, null, 2));
+        process.exit(0);
+      }
+
+      if (res.migrated.length === 0 && (!res.warnings || res.warnings.length === 0)) {
+        console.log(`✅ ${res.message || "Repository is already in canonical v1 format."}`);
+        process.exit(0);
+      }
+
+      if (dryRun) {
+        console.log("🧪 Dry run — no files modified.");
+        if (res.migrated.length === 0) {
+          console.log("   Nothing to migrate.");
+        } else {
+          console.log("   Would migrate:");
+          for (const item of res.migrated) {
+            console.log(`     - [${item.type}] ${item.path}`);
+            for (const change of item.changes || []) console.log(`         • ${change}`);
+          }
+        }
+      } else {
+        console.log("✅ Migration applied.");
+        for (const item of res.migrated) {
+          console.log(`   - [${item.type}] ${item.path}`);
+          for (const change of item.changes || []) console.log(`       • ${change}`);
+        }
+      }
+
+      if (res.warnings?.length) {
+        console.log("⚠️  Warnings:");
+        for (const w of res.warnings) console.log(`   - ${w}`);
+      }
+
+      process.exit(0);
+      break;
+    }
+
+    case "uninstall": {
+      const { values } = parseArgs({
+        args: args.slice(1),
+        options: {
+          "dry-run": { type: "boolean", short: "d" },
+          yes: { type: "boolean", short: "y" },
+          force: { type: "boolean", short: "f" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+
+      const dryRun = Boolean(values["dry-run"]);
+      const confirmed = Boolean(values.yes);
+      const force = Boolean(values.force);
+      const asJson = Boolean(values.json);
+
+      if (!dryRun && !confirmed) {
+        if (asJson) {
+          console.error(JSON.stringify({
+            ok: false,
+            error: "Refusing to uninstall without --yes. Pass --dry-run to preview, or --yes to confirm.",
+          }));
+        } else {
+          console.error("❌ Refusing to uninstall without --yes. Pass --dry-run to preview, or --yes to confirm.");
+        }
+        process.exit(1);
+      }
+
+      const { uninstallKit } = await import("../src/uninstall.mjs");
+      const res = uninstallKit(root, { dryRun, force });
+
+      if (!res.ok) {
+        if (asJson) {
+          console.log(JSON.stringify(res, null, 2));
+        } else {
+          console.error(`❌ ${res.error || "Uninstall failed."}`);
+        }
+        process.exit(1);
+      }
+
+      if (asJson) {
+        if (dryRun) {
+          console.log(JSON.stringify({ ok: true, dryRun: true, willRemove: res.willRemove }, null, 2));
+        } else {
+          console.log(JSON.stringify({ ok: true, removed: res.removed }, null, 2));
+        }
+        process.exit(0);
+      }
+
+      if (dryRun) {
+        console.log("🧪 Dry run — no files modified.");
+        console.log("   Would remove / clean:");
+        for (const item of res.willRemove) console.log(`     - ${item}`);
+        if (force && (!res.willRemove.some((p) => p.startsWith(".agent/rules") || p.startsWith(".agent/prompts") || p.startsWith(".agent/workflows") || p.startsWith(".agent/jules-queue")))) {
+          console.log("   (no legacy scaffold directories present)");
+        }
+      } else {
+        console.log("✅ Kit configuration uninstalled.");
+        console.log("   Removed / cleaned:");
+        for (const item of res.removed) console.log(`     - ${item}`);
+      }
+      process.exit(0);
+      break;
+    }
+
+    default: {
+      const knownTopCommands = [
+        ...new Set(
+          COMMAND_REGISTRY.flatMap((c) => [c.path[0], ...(c.shortcuts || [])]).filter(Boolean)
+        ),
+        "help",
+        "version",
+      ];
+      const { levenshteinDistance } = await import("../src/task-optimizer.mjs");
+      let closest = null;
+      let minDistance = Infinity;
+      for (const known of knownTopCommands) {
+        const dist = levenshteinDistance(command.toLowerCase(), known.toLowerCase());
+        if (dist < minDistance) {
+          minDistance = dist;
+          closest = known;
+        }
+      }
+      if (closest && minDistance <= 3) {
+        console.error(`Unknown command: "${command}". Did you mean "${closest}"?`);
+      } else {
+        console.error(`Unknown command: "${command}".`);
+      }
+      console.error(`Run 'agentctl --help' to see all available commands.`);
       process.exit(1);
+    }
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.74.0",
+  "version": "0.75.1",
   "description": "Zero-dependency safety gatekeeper, test oracle generator, and multi-agent coordination protocol for autonomous coding agents \u2014 Google Jules, Claude Code, Codex and Gemini CLI.",
   "repository": {
     "type": "git",