jules-orchestrator-kit 0.74.0 → 0.75.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.75.0] - 2026-09-28
+
+### Added
+- **Interactive Terminal Navigation Hub (`src/ops/tui-menu.mjs`)**: Added zero-external-dependency terminal UI hub accessible via `agentctl menu`, `tui`, `ui`, or `-i`, using Node.js ESM built-ins (`readline`, ANSI cursor escape sequences). Supports arrow-key navigation, hotkey selection, command preview, contextual execution, and direct handoff to interactive wizards.
+- **Fuzzy Typo Correction & Suggestions (`bin/agentctl.mjs`)**: Implemented Levenshtein-distance suggestion engine for unrecognized CLI commands, surfacing closest matches (e.g. `agentctl dsipatch` suggests `dispatch`).
+- **Actionable Scope Diagnostics & Protected Scope Flag (`src/wizard-task.mjs`)**: Added `--allow-protected` flag to `agentctl task create` alongside detailed diagnostic breakdowns of which paths are protected (e.g. `package.json`, `.agent/protected-paths.json`) when task objectives touch sensitive repository infrastructure.
+- **Task Payload Preview on Dry-Run (`bin/agentctl.mjs`, `src/engine.mjs`)**: `agentctl dispatch --dry-run` now prints formatted task payloads, verification commands, and risk tier assignments before execution.
+- **Maintainer Approval Path for Test Changes (`.github/workflows/agent-scope-guard.yml`, `scripts/ci-scope-guard.mjs`)**: Established narrow maintainer approval protocol (`allow-p:<HEAD_SHA>`, `allow-e:<HEAD_SHA>`) allowing verified modifications to test expectations or protected paths under explicit commit-bound review.
+
+### Fixed
+- **Goal Evidence Enforcement (`src/engine.mjs`)**: Disallowed silent early termination on goal tasks lacking explicit verification evidence.
+- **Test Environment Variable Bleed (`src/engine.mjs`)**: Sanitized test execution environment to prevent PR label bypass tokens from leaking into child test runs during gate evaluation.
+
 ## [0.74.0] - 2026-09-19
 
 ### Added

package/README.md

@@ -17,7 +17,7 @@ You can also run local checks without connecting an agent provider.
 `agentctl repair` explicitly for repair workflows. Provider output and passing
 checks still need review before merging.
 
-The current release is **v0.74.0**, a pre-1.0 release. A long-term stability policy is a
+The current release is **v0.75.0**, a pre-1.0 release. A long-term stability policy is a
 [v1.0 goal](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/ROADMAP_V1.md).
 
 ## Quickstart
@@ -174,7 +174,7 @@ npm run package-integrity
 npm run guard-reach
 ```
 
-The recorded baseline is **1553 unit tests across 204 suites**. Doc-sync compares
+The recorded baseline is **1650 unit tests across 210 suites**. Doc-sync compares
 that count with an actual run. Counts do not establish correctness for every
 provider or project. See
 [contributing](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/CONTRIBUTING.md)

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);
 
@@ -332,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" },
@@ -394,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,
       };
@@ -413,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
@@ -424,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!`);
@@ -690,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 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
@@ -1038,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);
@@ -1517,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,
@@ -1581,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);
@@ -1921,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),
@@ -2099,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,
         });
@@ -2129,6 +2229,7 @@ async function main() {
           repoless: values.repoless,
           interactive: isInteractive,
           dryRun: values["dry-run"],
+          allowProtected: Boolean(values["allow-protected"]),
         });
 
         if (values.json) {
@@ -2255,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;
@@ -2279,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);
@@ -2288,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);
@@ -3332,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);
+    }
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.74.0",
+  "version": "0.75.0",
   "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",

package/scripts/ci-scope-guard.mjs

@@ -22,8 +22,12 @@ import { normalizePath } from "../src/config.mjs";
 const EXIT_SCOPE_VIOLATION = 3;
 const EXIT_ERROR = 1;
 
-/** Label that lets a human consciously land a protected-path change. */
-export const BYPASS_LABEL = "allow-protected-paths";
+/**
+ * Primary label prefix that lets a human consciously land a protected-path change bound to commit SHA.
+ * Conforms to GitHub's 50-character maximum label limit: "allow-p:<40-hex-SHA>" is 48 characters.
+ */
+export const BYPASS_LABEL = "allow-p";
+export const LEGACY_BYPASS_LABEL = "allow-protected-paths";
 
 function gitShow(ref, path, cwd) {
   return execFileSync("git", ["show", `${ref}:${path}`], {
@@ -101,7 +105,18 @@ export function listChangedFiles(opts = {}) {
  */
 export function evaluateScopeGuard(files = [], patterns = [], opts = {}) {
   const labels = (opts.labels || []).map((l) => String(l).toLowerCase().trim());
-  const bypassed = labels.includes(BYPASS_LABEL);
+  const headSha = String(opts.headSha || "").trim().toLowerCase();
+
+  let bypassed = false;
+  if (headSha) {
+    if (/^[0-9a-f]{40}$/i.test(headSha)) {
+      const boundLabel = `${BYPASS_LABEL}:${headSha}`;
+      const legacyBoundLabel = `${LEGACY_BYPASS_LABEL}:${headSha}`;
+      bypassed = labels.includes(boundLabel) || labels.includes(legacyBoundLabel);
+    }
+  } else {
+    bypassed = labels.includes(BYPASS_LABEL) || labels.includes(LEGACY_BYPASS_LABEL);
+  }
 
   // Matching always runs at full strength; the label only decides whether a
   // match blocks. Passing `allowProtected` into checkScope instead would make
@@ -152,17 +167,25 @@ function main() {
   }
 
   const labels = parseLabels(process.env.PR_LABELS);
-  const result = evaluateScopeGuard(files, patterns, { labels });
+  const result = evaluateScopeGuard(files, patterns, { labels, headSha });
 
   console.log(`Protected patterns (${patterns.length}): ${patterns.join(", ")}`);
   console.log(`Changed files (${files.length}):`);
   for (const f of files) console.log(`  ${f}`);
 
+  const labelName = headSha ? `${BYPASS_LABEL}:${headSha}` : BYPASS_LABEL;
+  const legacyLabelName = headSha ? `${LEGACY_BYPASS_LABEL}:${headSha}` : LEGACY_BYPASS_LABEL;
+  const activeLabel = labels.includes(labelName)
+    ? labelName
+    : labels.includes(legacyLabelName)
+      ? legacyLabelName
+      : labelName;
+
   if (result.bypassed && result.violations.length > 0) {
     for (const v of result.violations) {
-      console.log(`::warning file=${v.file}::Protected path modified under "${BYPASS_LABEL}": ${v.reason}`);
+      console.log(`::warning file=${v.file}::Protected path modified under "${activeLabel}": ${v.reason}`);
     }
-    console.log(`\nLabel "${BYPASS_LABEL}" is present — ${result.violations.length} protected-path match(es) allowed by human review.`);
+    console.log(`\nLabel "${activeLabel}" is present — ${result.violations.length} protected-path match(es) allowed by human review.`);
     process.exit(0);
   }
 
@@ -176,7 +199,7 @@ function main() {
   }
   console.error(
     `::error::PR modifies ${result.violations.length} protected file(s). ` +
-      `Apply the "${BYPASS_LABEL}" label after human review to land this intentionally.`
+      `Apply the "${labelName}" label after human review to land this intentionally.`
   );
   process.exit(EXIT_SCOPE_VIOLATION);
 }