jules-orchestrator-kit 0.73.1 → 0.75.0

package/bin/agentctl.mjs

@@ -2,13 +2,14 @@
 
 import { parseArgs } from "node:util";
 import { readFileSync, existsSync, readdirSync, statSync, renameSync, mkdirSync } from "node:fs";
-import { join, resolve } from "node:path";
+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";
@@ -22,7 +23,18 @@ import { COMMAND_REGISTRY } from "../src/ops/command-registry.mjs";
 applyEnvAliases(process.env);
 
 const args = process.argv.slice(2);
-const command = args[0];
+const requestedCommand = args[0] || "";
+const gateCommands = new Set(["gate", "check", "audit"]);
+
+if (gateCommands.has(requestedCommand) && args.includes("--fix")) {
+  console.error("Error: `agentctl gate` is non-mutating; `--fix` no longer dispatches automated repairs.");
+  console.error("Run the gate normally, then use `agentctl repair` explicitly with the failure trace you want repaired.");
+  process.exit(2);
+}
+
+// `repair` is the canonical spelling; `fix` remains a 0.x compatibility
+// alias. Both route through the same existing implementation below.
+const command = requestedCommand;
 
 export const VERSION = KIT_VERSION;
 
@@ -78,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)");
@@ -257,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 = "";
@@ -294,8 +312,18 @@ async function main() {
   }
 
   const root = resolveRoot();
-  reapOrphanedIntents(root);
-  reapStaleMutexDirs(root);
+  // 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.
+  // 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);
 
   switch (command) {
@@ -316,6 +344,7 @@ async function main() {
           "auto-approve-plans": { type: "boolean" },
           "auto-approve": { type: "boolean" },
           "check-premise": { type: "boolean" },
+          "goal-check": { type: "string" },
           idempotent: { type: "boolean" },
           author: { type: "string" },
           "verify-cmd": { type: "string", short: "v" },
@@ -361,7 +390,7 @@ async function main() {
           console.error(
             `Error: Unknown agent role '${values.role}'. Expected matching prompt file in .agent/prompts/ (e.g. Auditor, Performance, Security, Hygiene, Testing).`
           );
-          console.error(`   Run 'agentctl init' to scaffold the shipped role prompts.`);
+          console.error(`   Use a canonical shipped role name or add a repository override under .agent/prompts/.`);
           process.exit(1);
         }
       }
@@ -378,6 +407,7 @@ async function main() {
         autoPr: values["auto-pr"],
         requirePlanApproval: autoApprove ? false : values["require-plan-approval"],
         checkPremise: values["check-premise"] || values.idempotent,
+        goalCheck: values["goal-check"],
         author: values.author,
         verifyCmd: values["verify-cmd"] || values.verify,
       };
@@ -397,7 +427,7 @@ async function main() {
         } 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
@@ -408,9 +438,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!`);
@@ -674,9 +711,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 let agentctl attempt the repair loop itself, pass: agentctl gate --fix\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
@@ -965,6 +1007,7 @@ async function main() {
       break;
     }
 
+    case "repair":
     case "fix": {
       const { repair, planTaskCreate, resolveRoot, redactSecrets } = await import("../index.mjs");
       const { values, positionals } = parseArgs({
@@ -996,7 +1039,7 @@ async function main() {
       }
 
       if (!errorInput.trim()) {
-        console.error("❌ Error: No error log or failure input provided. Pipe stdout/stderr via `npm test 2>&1 | agentctl fix` or provide --file/--input.");
+        console.error("❌ Error: No error log or failure input provided. Pipe stdout/stderr via `npm test 2>&1 | agentctl repair` or provide --file/--input.");
         process.exit(1);
       }
 
@@ -1021,17 +1064,53 @@ 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 }
         );
 
         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);
@@ -1500,6 +1579,7 @@ async function main() {
         options: {
           ttl: { type: "string" },
           pid: { type: "string" },
+          "dry-run": { type: "boolean", short: "d" },
           json: { type: "boolean", short: "j" },
         },
         allowPositionals: true,
@@ -1564,22 +1644,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);
@@ -1904,6 +2011,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),
@@ -1957,19 +2073,54 @@ async function main() {
         provider: values.provider,
         profile: values.profile,
         allowDefaults: true,
+        dryRun: values["dry-run"],
+        // --force is retained as the explicit 0.x compatibility path: it
+        // restores the legacy Jules manifest and full repository scaffold.
+        legacyManifest: values.force,
+        // JSON mode is a protocol surface: progress spinners must not prefix
+        // the payload with human-readable status lines.
+        stdout: values.json ? { write() {} } : process.stdout,
       });
 
-      // The wizard writes the manifest; the assets the CLI's documented
-      // features actually need — AGENTS.md, the role prompts, the guardrails,
-      // the gitignore entries — used to be scaffolded only by the separate
-      // `jules-init` binary that the README's quickstart never mentions.
-      const { scaffoldRepoAssets } = await import("../src/scaffold.mjs");
-      const scaffold = scaffoldRepoAssets(root, { force: values.force });
+      // Default init deliberately owns only the canonical config plus the
+      // runtime-state ignore block. The old full scaffold is opt-in via
+      // --force (and remains available through the shipped jules-init binary).
+      const {
+        ensureGitignore,
+        planGitignoreEntries,
+        planScaffoldRepoAssets,
+        scaffoldRepoAssets,
+      } = await import("../src/scaffold.mjs");
+      const plannedGitignore = planGitignoreEntries(root);
+      const legacyPlan = values.force ? planScaffoldRepoAssets(root, { force: true }) : { created: [], gitignore: plannedGitignore };
+      const scaffold =
+        values.force && !values["dry-run"]
+          ? scaffoldRepoAssets(root, { force: true })
+          : { created: legacyPlan.created, gitignore: plannedGitignore };
+      const gitignore =
+        values["dry-run"]
+          ? plannedGitignore
+          : values.force
+            ? scaffold.gitignore
+            : ensureGitignore(root);
+      const writes = [
+        ...res.writes.map((p) => (relative(root, p) || p).replaceAll("\\", "/")),
+        ...legacyPlan.created,
+        ...(plannedGitignore.length > 0 ? [".gitignore"] : []),
+      ].filter((p, index, all) => all.indexOf(p) === index);
 
       if (values.json) {
-        console.log(JSON.stringify({ ...res, scaffold }, null, 2));
+        console.log(JSON.stringify({ ...res, writes, gitignore }, null, 2));
       } else {
-        console.log(`✅ Onboarding complete! Manifest generated at ${res.configPath}`);
+        console.log(
+          values["dry-run"]
+            ? "🧪 Dry run — no files written."
+            : `✅ Onboarding complete! Manifest generated at ${res.configPath}`
+        );
+        if (values["dry-run"]) {
+          console.log("   Would write:");
+          for (const path of writes) console.log(`     - ${path}`);
+        }
         console.log(`   Tier: ${res.plan.tier.toUpperCase()} (${res.plan.limits.concurrency} worker(s), ${res.plan.limits.daily_tasks} daily tasks)`);
         {
           const { probeProvider } = await import("../src/provider-readiness.mjs");
@@ -1988,34 +2139,35 @@ async function main() {
           console.log(`   Verification Test Command : None detected (run "agentctl bootstrap" to create a test oracle)`);
         }
         console.log(`   Active Presets            : ${res.plan.presets.join(", ")}`);
-        for (const item of scaffold.created) {
-          console.log(`   Scaffolded                : ${item}`);
-        }
-        if (scaffold.gitignore.length > 0) {
-          console.log(`   Ignored runtime state     : ${scaffold.gitignore.length} entries added to .gitignore`);
-        }
-
-        // `.agent/config.yml` and `.agent/jules.yml` are both on the gate's deny
-        // list, by design — the agent must not edit its own rules. Leaving them
-        // uncommitted meant the very first `agentctl gate` rejected the working
-        // tree for files init had just written, which reads as the tool
-        // catching the user cheating on step three.
-        const rootContracts = ["SPEC.md", "CONSTRAINTS.md", "DESIGN.md"].filter((f) => existsSync(join(root, f)));
-        // A fresh `npm install`/`npm init -y` just created package manifests the
-        // scope rules `protect`. Leaving them out of the hint meant the very
-        // first `agentctl gate`/`agentctl task create` still rejected the tree
-        // even after the user committed exactly what this message listed. Fold
-        // the install-produced, currently-addable artifacts in so the suggested
-        // commit actually leaves the tree clean enough for step three.
-        const { addableOnboardingArtifacts } = await import("../src/git.mjs");
-        const filesToAdd = [".agent", "AGENTS.md", ...rootContracts, ...addableOnboardingArtifacts(root), ".gitignore"]
-          .filter((f) => existsSync(join(root, f)));
-        console.log(`\n   Commit the manifest and contracts so the gate does not read them as agent edits:`);
-        console.log(`     git add ${filesToAdd.join(" ")} && git commit -m "chore: add agent config"`);
-
-        const { resolveNextStep, renderNextStep } = await import("../src/ops/next-step.mjs");
-        const next = resolveNextStep(root);
-        console.log(renderNextStep({ version: VERSION, root, next, budgetLine: "" }));
+        if (values.force) {
+          const verb = values["dry-run"] ? "Would scaffold (legacy)" : "Scaffolded (legacy)";
+          for (const item of legacyPlan.created) {
+            console.log(`   ${verb.padEnd(26)}: ${item}`);
+          }
+        }
+        if (!values["dry-run"] && gitignore.length > 0) {
+          console.log(`   Ignored runtime state     : ${gitignore.length} entries added to .gitignore`);
+        }
+
+        if (!values["dry-run"]) {
+          // A fresh `npm install`/`npm init -y` may have created package
+          // manifests the scope rules protect. Include only files that really
+          // exist; minimal init itself owns .agent/config.yml and, when needed,
+          // the .gitignore runtime-state block.
+          const { addableOnboardingArtifacts } = await import("../src/git.mjs");
+          const filesToAdd = [
+            ".agent/config.yml",
+            ...(values.force ? [".agent/jules.yml", ...legacyPlan.created] : []),
+            ...addableOnboardingArtifacts(root),
+            ".gitignore",
+          ].filter((p, index, all) => all.indexOf(p) === index && existsSync(join(root, p)));
+          console.log(`\n   Commit the config so the gate does not read it as an agent edit:`);
+          console.log(`     git add ${filesToAdd.join(" ")} && git commit -m "chore: add agent config"`);
+
+          const { resolveNextStep, renderNextStep } = await import("../src/ops/next-step.mjs");
+          const next = resolveNextStep(root);
+          console.log(renderNextStep({ version: VERSION, root, next, budgetLine: "" }));
+        }
       }
       process.exit(0);
       break;
@@ -2046,6 +2198,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,
         });
@@ -2076,6 +2229,7 @@ async function main() {
           repoless: values.repoless,
           interactive: isInteractive,
           dryRun: values["dry-run"],
+          allowProtected: Boolean(values["allow-protected"]),
         });
 
         if (values.json) {
@@ -2202,8 +2356,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;
@@ -2226,7 +2459,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);
@@ -2235,7 +2468,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);
@@ -3279,10 +3512,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);
+    }
   }
 }