@dadado/agent-kit-cli 5.8.0 → 5.9.0

package/README.md

@@ -62,7 +62,7 @@ NO_COLOR=1 agent-kit
 # → plain text (no ANSI); also plain when stdout is not a TTY or CI=1
 ```
 
-Subcommands and `agent-kit --version` are unchanged. `agent-kit run <slash>` starts those project slashes headless from `.cursor/commands/` (numbered-list HITL). `/git-prod` and `/kit-prod` stay operator-gated and are omitted from that catalog.
+Subcommands and `agent-kit --version` are unchanged. `agent-kit run <slash>` starts those project slashes headless from `.cursor/commands/` (numbered-list HITL). `agent-kit run-plan-all` is a first-class alias of `agent-kit run run-plan-all`. Typing `/run-plan-all` in zsh is a filesystem path. `/git-prod` and `/kit-prod` stay operator-gated and are omitted from that catalog.
 
 On an interactive TTY, long-running commands (`init`, `install`, `doctor`, `update`, `run-plan` ticks) show an in-process ANSI spinner plus a rotating Mission Kit tip. Set `AGENT_KIT_REDUCED_MOTION=1` for static text on a capable TTY. Runtime dependencies stay `@clack/prompts`, `citty`, and `kolorist` (no `ora` / `figlet` / `chalk` / `ink`). Window titles for `agent-kit dashboard` and `agent-kit dashboard-broadcast` use the workspace basename, not the CLI package folder.
 
@@ -80,6 +80,7 @@ On an interactive TTY, long-running commands (`init`, `install`, `doctor`, `upda
 | `agent-kit add <id>` | Install a skill or L1 pack |
 | `agent-kit run <slash>` | One headless session from an L0 slash file (numbered-list HITL; never git-prod) |
 | `agent-kit run-plan` | Headless continuous plan runner (never promotes to production) |
+| `agent-kit run-plan-all` | Headless `/run-plan-all` queue from the L0 file (same as `run run-plan-all`; never git-prod) |
 
 Run `agent-kit --help` or `agent-kit <command> --help` for the full surface.
 

package/dist/index.js

@@ -273,7 +273,8 @@ var KNOWN_SHIPPED_OVERLAY_HASHES = /* @__PURE__ */ new Set([
   "3a88df22375f90a3a6743f50d9a01129e0373f4ca8dff03fb744c1de3c149409",
   "481a9994ccecaa611173f9ef91a1dbe7458d89758c6a6b5e7c3bbbbf460888ce",
   "691d91fd1e9032b6f9315f29348d4473201917da257258afd74eb954298d8d71",
-  "ab0808b7dbc333e523b87b126bb655353cde2574db30d849cc9c9037843bef8c"
+  "ab0808b7dbc333e523b87b126bb655353cde2574db30d849cc9c9037843bef8c",
+  "85514e26af694bbe38e7ddf625710a32719ddf6afc173843c9cdfbffdad8e466"
 ]);
 
 // src/lifecycle/paths.ts
@@ -942,6 +943,9 @@ function loadPackageVersion() {
 }
 var KIT_VERSION = loadPackageVersion();
 var KIT_PACKAGE_SPEC = "@dadado/agent-kit-cli";
+function pinnedCliSpec(version = KIT_VERSION) {
+  return `${KIT_PACKAGE_SPEC}@${version}`;
+}
 
 // src/manifest/index.ts
 import path6 from "path";
@@ -3659,21 +3663,81 @@ import { constants as constants3, access as access6, readFile as readFile10, sta
 import { homedir as homedir2 } from "os";
 import path16 from "path";
 var MIN_NODE_MAJOR = 20;
-async function checkBinOnPath(binName, env, platform) {
+var CLI_PACKAGE_JSON_REL = path16.join(
+  "lib",
+  "node_modules",
+  "@dadado",
+  "agent-kit-cli",
+  "package.json"
+);
+var DIST_INDEX_RE = /(?:\$\{basedir\}|\$basedir)?[^'"\s;]*dist\/index\.js/g;
+function extractDistIndexFromBinScript(contents) {
+  const found = [];
+  DIST_INDEX_RE.lastIndex = 0;
+  for (const match of contents.matchAll(DIST_INDEX_RE)) {
+    const raw = match[0]?.trim();
+    if (raw) found.push(raw.replace(/\\/g, "/"));
+  }
+  return found;
+}
+function expandBinDirVars(raw, binDir) {
+  return raw.replace(/\$\{basedir\}/g, binDir).replace(/\$basedir/g, binDir);
+}
+function packageJsonFromDistIndex(distIndex) {
+  return path16.join(path16.dirname(distIndex), "..", "package.json");
+}
+function parsePackageVersion(contents) {
+  try {
+    const parsed = JSON.parse(contents);
+    return typeof parsed.version === "string" && parsed.version.length > 0 ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+async function readBinVersion(binPath, options = {}) {
+  const readFileImpl = options.readFileImpl ?? ((filePath) => readFile10(filePath, "utf8"));
+  const binDir = path16.dirname(binPath);
+  const candidates = [
+    path16.join(binDir, "..", CLI_PACKAGE_JSON_REL),
+    path16.join(binDir, "..", "node_modules", "@dadado", "agent-kit-cli", "package.json")
+  ];
+  try {
+    const contents = await readFileImpl(binPath);
+    for (const raw of extractDistIndexFromBinScript(contents)) {
+      const distIndex = path16.resolve(binDir, expandBinDirVars(raw, binDir));
+      candidates.push(packageJsonFromDistIndex(distIndex));
+    }
+  } catch {
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const candidate2 of candidates) {
+    const resolved = path16.resolve(candidate2);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    try {
+      const version = parsePackageVersion(await readFileImpl(resolved));
+      if (version) return version;
+    } catch {
+    }
+  }
+  return null;
+}
+async function resolveBinOnPath(binName, env, platform) {
   const pathVar = env.PATH ?? env.Path ?? "";
-  if (!pathVar) return false;
+  if (!pathVar) return null;
   const dirs = pathVar.split(path16.delimiter).filter(Boolean);
   const candidates = platform === "win32" ? [binName, `${binName}.cmd`, `${binName}.exe`, `${binName}.bat`] : [binName];
   for (const dir of dirs) {
     for (const candidate2 of candidates) {
+      const abs = path16.join(dir, candidate2);
       try {
-        await access6(path16.join(dir, candidate2), platform === "win32" ? void 0 : constants3.X_OK);
-        return true;
+        await access6(abs, platform === "win32" ? void 0 : constants3.X_OK);
+        return abs;
       } catch {
       }
     }
   }
-  return false;
+  return null;
 }
 function isNodeVersionOk(nodeVersion, minMajor = MIN_NODE_MAJOR) {
   const match = /^v?(\d+)/.exec(nodeVersion);
@@ -3769,8 +3833,8 @@ async function assessEnvironment(options = {}) {
   const nodeVersion = options.nodeVersion ?? process.version;
   const homeDir = options.homeDir ?? homedir2();
   const binName = options.binName ?? "agent-kit";
-  const [binOnPath, npmPrefix] = await Promise.all([
-    checkBinOnPath(binName, env, platform).catch(() => false),
+  const [binPath, npmPrefix] = await Promise.all([
+    resolveBinOnPath(binName, env, platform).catch(() => null),
     checkNpmPrefixWritable(options).catch(
       () => ({
         prefix: null,
@@ -3779,8 +3843,11 @@ async function assessEnvironment(options = {}) {
       })
     )
   ]);
+  const binVersion = binPath ? await readBinVersion(binPath, options).catch(() => null) : null;
   return {
-    binOnPath,
+    binOnPath: binPath != null,
+    binPath,
+    binVersion,
     npmPrefixWritable: npmPrefix.writable,
     npmPrefix,
     nodeVersionOk: isNodeVersionOk(nodeVersion),
@@ -5274,7 +5341,8 @@ function printDoctorSummary(result) {
     }
   }
   console.log("environment:");
-  console.log(`  - bin on PATH (agent-kit): ${result.env.binOnPath ? "ok" : "MISSING"}`);
+  const pathLabel = result.env.binOnPath ? `ok (v${result.env.binVersion ?? "unknown"} at ${result.env.binPath})` : "MISSING";
+  console.log(`  - bin on PATH (agent-kit): ${pathLabel}`);
   console.log(
     `  - npm prefix writable: ${result.env.npmPrefixWritable ? "ok" : "BLOCKED"}${result.env.npmPrefix.prefix ? ` (${result.env.npmPrefix.prefix})` : ""}`
   );
@@ -6743,6 +6811,10 @@ var hookCommand = defineCommand10({
 import { intro, outro } from "@clack/prompts";
 import { defineCommand as defineCommand12 } from "citty";
 
+// src/lifecycle/path-cli.ts
+import { spawn as spawn6 } from "child_process";
+import path32 from "path";
+
 // src/utils/terminal.ts
 import { readdir as readdir6 } from "fs/promises";
 import { homedir as homedir3 } from "os";
@@ -6928,18 +7000,122 @@ function classifyInstallError(err) {
   };
 }
 
+// src/lifecycle/path-cli.ts
+function npxPinned(runtimeVersion, subcommand) {
+  return `npx -y ${pinnedCliSpec(runtimeVersion)} ${subcommand}`;
+}
+function isBinUnderPrefix(binPath, prefix) {
+  const bin = path32.resolve(binPath);
+  const root = path32.resolve(prefix);
+  return bin === root || bin.startsWith(`${root}${path32.sep}`);
+}
+function pathCliStatus(env, runtimeVersion) {
+  if (!env.binOnPath || !env.binPath) return "missing";
+  const running = normalizeSemver(runtimeVersion);
+  const pathVer = env.binVersion ? normalizeSemver(env.binVersion) : null;
+  if (!pathVer || !running) return "unknown";
+  try {
+    return compareSemver(pathVer, running) >= 0 ? "current" : "behind";
+  } catch {
+    return "unknown";
+  }
+}
+function driftLines(env, runtimeVersion) {
+  const pathVer = env.binVersion ?? "unknown";
+  const where = env.binPath ?? "(unresolved)";
+  return [
+    `This CLI is v${runtimeVersion}. PATH \`agent-kit\` is v${pathVer} at:`,
+    `  ${where}`,
+    "Do not run bare `agent-kit update` or `init` from that binary. It re-stamps the old version.",
+    "Keep using the pinned npx form until PATH matches:",
+    `  ${npxPinned(runtimeVersion, "update")}`,
+    `  ${npxPinned(runtimeVersion, "status")}`
+  ];
+}
+function isShadow(env) {
+  if (!env.binPath || !env.npmPrefix.prefix) return false;
+  return !isBinUnderPrefix(env.binPath, env.npmPrefix.prefix);
+}
+async function spawnNpmGlobalInstall(spec) {
+  return new Promise((resolve3) => {
+    const child = spawn6("npm", ["i", "-g", spec], { stdio: "inherit" });
+    child.on("error", (error) => resolve3({ ok: false, error }));
+    child.on("close", (code) => {
+      if (code === 0) resolve3({ ok: true });
+      else resolve3({ ok: false, error: new Error(`npm exited with code ${code ?? "unknown"}`) });
+    });
+  });
+}
+async function syncPathCliToRuntime(options = {}) {
+  const runtimeVersion = options.runtimeVersion ?? KIT_VERSION;
+  const assess = options.assessEnvironmentImpl ?? assessEnvironment;
+  let env = options.env ?? await assess();
+  const autoInstall = options.autoInstall ?? !isNonInteractive();
+  const lines = [];
+  let status = pathCliStatus(env, runtimeVersion);
+  if (status === "current") {
+    return { status, env, upgraded: false, lines };
+  }
+  if (status === "behind" || status === "unknown") {
+    lines.push(...driftLines(env, runtimeVersion));
+    if (isShadow(env)) {
+      lines.push(
+        "That PATH hit is not npm's global bin, so `npm i -g` may not replace it.",
+        "Run `hash -r` and `which -a agent-kit`. Put npm's global bin first, or remove the stale shim."
+      );
+    }
+  }
+  if (!autoInstall) {
+    return { status, env, upgraded: false, lines };
+  }
+  if (status === "missing") {
+    lines.push("No bare `agent-kit` on PATH yet (npx is ephemeral).");
+  }
+  if (!env.npmPrefixWritable) {
+    lines.push(
+      "npm's global prefix is not writable, so this process cannot upgrade PATH.",
+      `Run ${npxPinned(runtimeVersion, "setup-global")} (or fix prefix permissions).`
+    );
+    return { status, env, upgraded: false, lines };
+  }
+  const spec = pinnedCliSpec(runtimeVersion);
+  const install = options.npmInstallImpl ?? spawnNpmGlobalInstall;
+  lines.push(`Installing ${spec} into the writable npm prefix...`);
+  const outcome = await install(spec);
+  if (!outcome.ok) {
+    const detail = outcome.error instanceof Error ? outcome.error.message : "npm i -g failed";
+    lines.push(`Global install failed: ${detail}`);
+    return { status, env, upgraded: false, lines };
+  }
+  env = await assess();
+  status = pathCliStatus(env, runtimeVersion);
+  if (status === "current") {
+    lines.push(
+      `PATH \`agent-kit\` is now v${env.binVersion ?? runtimeVersion}.`,
+      "If this shell still shows the old version, run `hash -r` or open a new terminal."
+    );
+    return { status, env, upgraded: true, lines };
+  }
+  lines.push(
+    `Installed ${spec}, but PATH still resolves to v${env.binVersion ?? "unknown"} at:`,
+    `  ${env.binPath ?? "(unresolved)"}`,
+    "Run `hash -r` and `which -a agent-kit`. Until PATH matches, keep using the npx pin above."
+  );
+  return { status, env, upgraded: true, lines };
+}
+
 // src/commands/install.ts
-import path38 from "path";
+import path39 from "path";
 import { defineCommand as defineCommand11 } from "citty";
 import { bold, cyan as cyan3, green as green2, options as koloristOptions2 } from "kolorist";
 
 // src/generator/personalization.ts
 import { readFile as readFile19, writeFile as writeFile12 } from "fs/promises";
-import path36 from "path";
+import path37 from "path";
 
 // src/generator/claude-command-adapters.ts
 import { readFile as readFile17, readdir as readdir7, writeFile as writeFile8 } from "fs/promises";
-import path32 from "path";
+import path33 from "path";
 var CURSOR_COMMANDS_DIR_REL = ".cursor/commands";
 var CLAUDE_COMMANDS_DIR_REL = ".claude/commands";
 var RESERVED_ADAPTER_NAMES = /* @__PURE__ */ new Set(["agent-kit"]);
@@ -6968,7 +7144,7 @@ Adapter rules (Claude Code CLI):
 `;
 }
 async function discoverInstalledCommands(rootDir) {
-  const dir = path32.join(rootDir, CURSOR_COMMANDS_DIR_REL);
+  const dir = path33.join(rootDir, CURSOR_COMMANDS_DIR_REL);
   let entries;
   try {
     entries = (await readdir7(dir)).filter((f) => f.endsWith(".md"));
@@ -6980,7 +7156,7 @@ async function discoverInstalledCommands(rootDir) {
     const name = file.slice(0, -3);
     if (RESERVED_ADAPTER_NAMES.has(name)) continue;
     try {
-      const raw = await readFile17(path32.join(dir, file), "utf8");
+      const raw = await readFile17(path33.join(dir, file), "utf8");
       const parsed = parseCommandFrontmatter(name, raw);
       if (parsed) commands.push(parsed);
     } catch {
@@ -6995,11 +7171,11 @@ async function generateClaudeCommandAdapters(rootDir) {
   const results = [];
   let ledgerDirty = false;
   for (const command of commands) {
-    const relPath = path32.posix.join(CLAUDE_COMMANDS_DIR_REL, `${command.name}.md`);
+    const relPath = path33.posix.join(CLAUDE_COMMANDS_DIR_REL, `${command.name}.md`);
     const rendered = renderClaudeCommandAdapter(command);
-    const abs = path32.join(rootDir, relPath);
+    const abs = path33.join(rootDir, relPath);
     if (!await fileExists(abs)) {
-      await ensureDir(path32.dirname(abs));
+      await ensureDir(path33.dirname(abs));
       await writeFile8(abs, rendered, "utf8");
       ledger.hashes[relPath] = contentHash(rendered);
       ledgerDirty = true;
@@ -7030,7 +7206,7 @@ async function generateClaudeCommandAdapters(rootDir) {
 
 // src/generator/claude-kit-load.ts
 import { writeFile as writeFile9 } from "fs/promises";
-import path33 from "path";
+import path34 from "path";
 var CLAUDE_MD_REL = "CLAUDE.md";
 var AGENT_KIT_COMMAND_REL = ".claude/commands/agent-kit.md";
 function renderClaudeMd() {
@@ -7086,11 +7262,11 @@ Non-goals: not audits / \`/plan-external-review\`, not a second tick dialect (\`
 `;
 }
 async function writeUnlessExists(rootDir, relativePath, content) {
-  const target = path33.join(rootDir, relativePath);
+  const target = path34.join(rootDir, relativePath);
   if (await fileExists(target)) {
     return { relativePath, status: "skipped-customized" };
   }
-  await ensureDir(path33.dirname(target));
+  await ensureDir(path34.dirname(target));
   await writeFile9(target, content, "utf8");
   return { relativePath, status: "applied" };
 }
@@ -7103,7 +7279,7 @@ async function generateClaudeKitLoadArtifacts(rootDir) {
 
 // src/generator/claude-session-start-hook.ts
 import { readFile as readFile18, writeFile as writeFile10 } from "fs/promises";
-import path34 from "path";
+import path35 from "path";
 var CLAUDE_SETTINGS_REL = ".claude/settings.json";
 var RESOLVE_AGENT_KIT_REL = ".cursor/hooks/agent/resolve-agent-kit.sh";
 var SESSION_START_HOOK_MARKER = "hook session-start --format claude";
@@ -7178,7 +7354,7 @@ function instructionsBlock(entry) {
   ].join("\n");
 }
 async function writeClaudeSessionStartHook(rootDir) {
-  const abs = path34.join(rootDir, CLAUDE_SETTINGS_REL);
+  const abs = path35.join(rootDir, CLAUDE_SETTINGS_REL);
   let existing = null;
   try {
     existing = await readFile18(abs, "utf8");
@@ -7196,14 +7372,14 @@ async function writeClaudeSessionStartHook(rootDir) {
   if (merged.status === "unchanged") {
     return { relativePath: CLAUDE_SETTINGS_REL, status: "unchanged" };
   }
-  await ensureDir(path34.dirname(abs));
+  await ensureDir(path35.dirname(abs));
   await writeFile10(abs, merged.content, "utf8");
   return { relativePath: CLAUDE_SETTINGS_REL, status: merged.status };
 }
 
 // src/generator/vscode.ts
 import { writeFile as writeFile11 } from "fs/promises";
-import path35 from "path";
+import path36 from "path";
 
 // src/generator/platform.ts
 function gitProviderLabel(profile) {
@@ -7227,10 +7403,10 @@ function prTerminology(profile) {
 // src/generator/vscode.ts
 async function generateVSCodeArtifacts(profile) {
   const results = [];
-  const vscodeDir = path35.join(profile.rootDir, ".vscode");
-  const githubDir = path35.join(profile.rootDir, ".github");
+  const vscodeDir = path36.join(profile.rootDir, ".vscode");
+  const githubDir = path36.join(profile.rootDir, ".github");
   await Promise.all([ensureDir(vscodeDir), ensureDir(githubDir)]);
-  const settingsPath = path35.join(vscodeDir, "settings.json");
+  const settingsPath = path36.join(vscodeDir, "settings.json");
   if (await fileExists(settingsPath)) {
     results.push({ relativePath: ".vscode/settings.json", status: "skipped-customized" });
   } else {
@@ -7254,7 +7430,7 @@ async function generateVSCodeArtifacts(profile) {
   }
   const provider = gitProviderLabel(profile);
   const prTerm = prTerminology(profile);
-  const copilotPath = path35.join(githubDir, "copilot-instructions.md");
+  const copilotPath = path36.join(githubDir, "copilot-instructions.md");
   if (await fileExists(copilotPath)) {
     results.push({ relativePath: ".github/copilot-instructions.md", status: "skipped-customized" });
   } else {
@@ -7272,7 +7448,7 @@ async function generateVSCodeArtifacts(profile) {
     results.push({ relativePath: ".github/copilot-instructions.md", status: "applied" });
   }
   if (profile.ide.plan === "vscode-pro") {
-    const securityPath = path35.join(vscodeDir, "security-review.agent.md");
+    const securityPath = path36.join(vscodeDir, "security-review.agent.md");
     if (await fileExists(securityPath)) {
       results.push({
         relativePath: ".vscode/security-review.agent.md",
@@ -7484,7 +7660,7 @@ function renderProjectContext(profile, skillItems = []) {
 `;
 }
 async function createOwnedFile(rootDir, relativePath, content, evidence) {
-  const target = path36.join(rootDir, relativePath);
+  const target = path37.join(rootDir, relativePath);
   if (await fileExists(target)) {
     return {
       kind: "file",
@@ -7494,7 +7670,7 @@ async function createOwnedFile(rootDir, relativePath, content, evidence) {
       evidence
     };
   }
-  await ensureDir(path36.dirname(target));
+  await ensureDir(path37.dirname(target));
   await writeFile12(target, content, "utf8");
   return {
     kind: "file",
@@ -7511,7 +7687,7 @@ async function packTargets(registryRoot, packId) {
 async function existingTargets(projectRoot, targets) {
   const checks = await Promise.all(
     targets.map(
-      async (target) => await fileExists(path36.join(projectRoot, target)) ? target : null
+      async (target) => await fileExists(path37.join(projectRoot, target)) ? target : null
     )
   );
   return checks.filter((target) => target !== null);
@@ -7533,14 +7709,14 @@ async function applyPersonalization(input) {
         componentResults.push({ ...item, status: "unavailable" });
         continue;
       }
-      const target = path36.posix.join(
+      const target = path37.posix.join(
         ".cursor",
         "skills",
         skill.path.includes("/core/") ? "core" : "community",
         skill.id,
         "SKILL.md"
       );
-      if (await fileExists(path36.join(input.rootDir, target))) {
+      if (await fileExists(path37.join(input.rootDir, target))) {
         componentResults.push({ ...item, status: "skipped-customized", path: target });
         protectedPaths.add(target);
         continue;
@@ -7685,7 +7861,7 @@ async function applyPersonalization(input) {
     protectedPaths: [...protectedPaths].sort(),
     ...claudeSessionStartInstructions ? { claudeSessionStartInstructions } : {}
   };
-  await writeJson(path36.join(input.rootDir, RESULT_PATH), result);
+  await writeJson(path37.join(input.rootDir, RESULT_PATH), result);
   return {
     result,
     manifest: {
@@ -7703,7 +7879,7 @@ async function applyPersonalization(input) {
   };
 }
 async function readRepositoryProfile(rootDir) {
-  const target = path36.join(rootDir, ".cursor/agent-kit.config.json");
+  const target = path37.join(rootDir, ".cursor/agent-kit.config.json");
   if (!await fileExists(target)) return null;
   return JSON.parse(await readFile19(target, "utf8"));
 }
@@ -7711,16 +7887,16 @@ async function readRepositoryProfile(rootDir) {
 // src/lifecycle/onboard-migration.ts
 import { createHash as createHash4 } from "crypto";
 import { readFile as readFile20, unlink } from "fs/promises";
-import path37 from "path";
+import path38 from "path";
 var LEGACY_ONBOARD_PATH = ".cursor/commands/onboard.md";
 var NAMESPACED_ONBOARD_PATH = ".cursor/commands/agent-kit-onboard.md";
 var MANAGED_LEGACY_HASHES = /* @__PURE__ */ new Set([
   "b274a68941813f19b185893cb7c5561dff027f53270890029992f208e24992fe"
 ]);
 async function migrateLegacyOnboardCommand(projectRoot, managedHashes = MANAGED_LEGACY_HASHES) {
-  const legacyPath = path37.join(projectRoot, LEGACY_ONBOARD_PATH);
+  const legacyPath = path38.join(projectRoot, LEGACY_ONBOARD_PATH);
   if (!await fileExists(legacyPath)) return "absent";
-  const namespacedPath = path37.join(projectRoot, NAMESPACED_ONBOARD_PATH);
+  const namespacedPath = path38.join(projectRoot, NAMESPACED_ONBOARD_PATH);
   if (!await fileExists(namespacedPath)) return "preserved-customized";
   const content = await readFile20(legacyPath);
   const hash = createHash4("sha256").update(content).digest("hex");
@@ -7810,8 +7986,15 @@ function paint(fn, text) {
 function printInstallEpilogue(env, options = {}) {
   const print = options.print ?? ((line) => console.log(line));
   const color = options.color ?? shouldUseWelcomeColor();
-  if (env.binOnPath) {
-    const line = "`agent-kit` is on PATH \u2014 run it directly, e.g. `agent-kit doctor`.";
+  const runtimeVersion = options.runtimeVersion ?? KIT_VERSION;
+  const status = pathCliStatus(env, runtimeVersion);
+  if (status === "current") {
+    const line = `PATH \`agent-kit\` is v${env.binVersion ?? runtimeVersion}. Run it directly, e.g. \`agent-kit doctor\`.`;
+    print(color ? paint(green2, line) : line);
+    return;
+  }
+  if (status === "behind" || status === "unknown") {
+    const line = `Keep using ${npxPinned(runtimeVersion, "<subcommand>")} until PATH is v${runtimeVersion}.`;
     print(color ? paint(green2, line) : line);
     return;
   }
@@ -7821,11 +8004,11 @@ function printInstallEpilogue(env, options = {}) {
     'If you try `agent-kit <subcommand>` next, you will see "command not',
     'found". Pick one:',
     "",
-    "  1. Keep using npx \u2014 works right now, no action needed",
-    "     npx @dadado/agent-kit-cli@latest <subcommand>",
+    "  1. Keep using npx (works right now, no action needed)",
+    `     ${npxPinned(runtimeVersion, "<subcommand>")}`,
     "",
     "  2. Put a bare `agent-kit` on PATH",
-    "     npx @dadado/agent-kit-cli@latest setup-global",
+    `     ${npxPinned(runtimeVersion, "setup-global")}`,
     "     (fixes a root-owned npm prefix if that's the blocker, or just installs)",
     "",
     "  3. Manual steps",
@@ -7833,7 +8016,7 @@ function printInstallEpilogue(env, options = {}) {
     "       mkdir -p ~/.npm-global",
     '       npm config set prefix "~/.npm-global"',
     '       export PATH="~/.npm-global/bin:$PATH"',
-    "       npm i -g @dadado/agent-kit-cli@latest"
+    `       npm i -g ${pinnedCliSpec(runtimeVersion)}`
   ];
   print(color ? paint(cyan3, divider) : divider);
   const heading = "Heads up: a bare `agent-kit` command won't work yet";
@@ -7844,10 +8027,12 @@ function printInstallEpilogue(env, options = {}) {
 async function printPostInstallSummary(result) {
   printReadinessNarrative(result);
   const env = await assessEnvironment();
-  printInstallEpilogue(env);
+  const sync = await syncPathCliToRuntime({ runtimeVersion: KIT_VERSION, env });
+  for (const line of sync.lines) console.log(line);
+  printInstallEpilogue(sync.env, { runtimeVersion: KIT_VERSION });
 }
 async function performInstall(options) {
-  const projectRoot = path38.resolve(options.cwd);
+  const projectRoot = path39.resolve(options.cwd);
   const packs = parsePackList(options.pack);
   const existing = await loadAgentKitManifest(projectRoot);
   const registry = await resolveRegistryFromCli({
@@ -7970,6 +8155,7 @@ ${err.recovery}
       throw err;
     }
     logger.info(`Installing into: ${projectRoot}`);
+    logger.info(`CLI v${KIT_VERSION}`);
     await warnIfRunningCliBehindNpm(projectRoot, { warn: (message) => logger.warn(message) });
     const packs = parsePackList(args.pack);
     for (const id of packs) {
@@ -8072,12 +8258,13 @@ ${err.recovery}
       logger.success(`L0 and readiness prepared in ${result.projectRoot}`);
       const nextStep = nextStepAfterInstall(pending);
       const env = await assessEnvironment();
+      const sync = await syncPathCliToRuntime({ runtimeVersion: KIT_VERSION, env });
+      for (const line of sync.lines) console.log(line);
+      printInstallEpilogue(sync.env, { runtimeVersion: KIT_VERSION });
       if (!nonInteractive) {
-        printInstallEpilogue(env);
         outro(nextStep);
       } else {
         logger.info(nextStep);
-        printInstallEpilogue(env);
       }
     } catch (err) {
       const hint = classifyInstallError(err);
@@ -8250,7 +8437,7 @@ function shouldLiveRefresh(opts) {
 // src/mission-control/snapshot.ts
 import { execFile as execFile6 } from "child_process";
 import { access as access8 } from "fs/promises";
-import path39 from "path";
+import path40 from "path";
 
 // ../../dashboard/lib/live-refresh.mjs
 import { join, resolve as resolve2 } from "path";
@@ -8283,7 +8470,7 @@ async function firstExisting2(candidates) {
   for (const candidate2 of candidates) {
     try {
       await access8(candidate2);
-      return path39.resolve(candidate2);
+      return path40.resolve(candidate2);
     } catch {
     }
   }
@@ -8292,7 +8479,7 @@ async function firstExisting2(candidates) {
 async function findDashboardDataScript(cwd, env = process.env, options = {}) {
   const startPath = await findDashboardStart(cwd, env, options);
   if (startPath) {
-    const sibling = path39.join(path39.dirname(startPath), "dashboard-data.mjs");
+    const sibling = path40.join(path40.dirname(startPath), "dashboard-data.mjs");
     try {
       await access8(sibling);
       return sibling;
@@ -8307,7 +8494,7 @@ async function loadDashboardSnapshot(opts) {
   const env = opts.env ?? process.env;
   const timeout = dataScriptTimeoutMs(env);
   const run = opts.execFileFn ?? execFile6;
-  const snapshotRoot = path39.resolve(opts.snapshotRoot);
+  const snapshotRoot = path40.resolve(opts.snapshotRoot);
   return new Promise((resolve3) => {
     run(
       process.execPath,
@@ -8615,13 +8802,13 @@ var missionControlCommand = defineCommand13({
 });
 
 // src/commands/monitors.ts
-import path41 from "path";
+import path42 from "path";
 import { defineCommand as defineCommand14 } from "citty";
 
 // src/invariants/monitors-untriaged.ts
 import { execFile as execFile7 } from "child_process";
 import { readFile as readFile21, readdir as readdir8, stat as stat5 } from "fs/promises";
-import path40 from "path";
+import path41 from "path";
 import { promisify as promisify6 } from "util";
 
 // src/invariants/triage-heading.ts
@@ -8662,7 +8849,7 @@ async function gitFreshMonitorNames(rootDir) {
     for (const line of stdout.split("\n")) {
       if (!line.trim()) continue;
       const file = line.slice(3).trim().replace(/^.* -> /, "");
-      const base = path40.basename(file);
+      const base = path41.basename(file);
       if (base.startsWith("plan-monitor-") && base.endsWith(".md")) {
         names.add(base);
       }
@@ -8685,13 +8872,13 @@ function monitorSlugFromName(fileName) {
   return fileName.replace(/^plan-monitor-/, "").replace(/\.md$/, "").toLowerCase();
 }
 async function selectUntriagedMonitors(rootDir) {
-  const root = path40.resolve(rootDir);
-  const memoryDir = path40.join(root, ".cursor", "memory");
+  const root = path41.resolve(rootDir);
+  const memoryDir = path41.join(root, ".cursor", "memory");
   const allNames = await listMonitorFiles(memoryDir);
   const selectionOrder = ["git-fresh", "handoff-aligned", "untriaged-scan"];
   const byName = /* @__PURE__ */ new Map();
   for (const name of allNames) {
-    const abs = path40.join(memoryDir, name);
+    const abs = path41.join(memoryDir, name);
     try {
       const [content, st] = await Promise.all([readFile21(abs, "utf8"), stat5(abs)]);
       byName.set(name, { content, mtimeMs: st.mtimeMs });
@@ -8706,7 +8893,7 @@ async function selectUntriagedMonitors(rootDir) {
   const gitFreshSet = [...gitFresh].filter(untriaged).sort();
   let handoff = "";
   try {
-    handoff = await readFile21(path40.join(root, ".cursor", "HANDOFF.md"), "utf8");
+    handoff = await readFile21(path41.join(root, ".cursor", "HANDOFF.md"), "utf8");
   } catch {
     handoff = "";
   }
@@ -8726,8 +8913,8 @@ async function selectUntriagedMonitors(rootDir) {
     const row = byName.get(name);
     if (!row) continue;
     entries.push({
-      path: path40.join(memoryDir, name),
-      relativePath: path40.relative(root, path40.join(memoryDir, name)).split(path40.sep).join("/"),
+      path: path41.join(memoryDir, name),
+      relativePath: path41.relative(root, path41.join(memoryDir, name)).split(path41.sep).join("/"),
       mtimeMs: row.mtimeMs,
       hasTriageHeading: false,
       hasOpenGaps: hasOpenGaps(row.content),
@@ -8773,7 +8960,7 @@ var monitorsCommand = defineCommand14({
       process.exitCode = 2;
       return;
     }
-    const result = await selectUntriagedMonitors(path41.resolve(args.cwd));
+    const result = await selectUntriagedMonitors(path42.resolve(args.cwd));
     if (args.json) {
       console.log(JSON.stringify(result, null, 2));
       return;
@@ -8789,7 +8976,7 @@ var monitorsCommand = defineCommand14({
 });
 
 // src/commands/plan-index.ts
-import path42 from "path";
+import path43 from "path";
 import { defineCommand as defineCommand15 } from "citty";
 var planIndexCommand = defineCommand15({
   meta: {
@@ -8808,7 +8995,7 @@ var planIndexCommand = defineCommand15({
     }
   },
   async run({ args }) {
-    const root = path42.resolve(args.cwd);
+    const root = path43.resolve(args.cwd);
     const index = await writePlanIndex(root);
     if (args.json) {
       console.log(JSON.stringify(index, null, 2));
@@ -8824,14 +9011,14 @@ var planIndexCommand = defineCommand15({
 });
 
 // src/commands/run-plan.ts
-import path48 from "path";
+import path49 from "path";
 import { defineCommand as defineCommand16 } from "citty";
 
 // src/plan-loop/backends.ts
-import { execFileSync as execFileSync2, spawn as spawn6 } from "child_process";
+import { execFileSync as execFileSync2, spawn as spawn7 } from "child_process";
 import { createWriteStream } from "fs";
 import { access as access9 } from "fs/promises";
-import path43 from "path";
+import path44 from "path";
 import { StringDecoder } from "string_decoder";
 var CLAUDE_ENV_PASSTHROUGH = [
   "ANTHROPIC_BASE_URL",
@@ -8987,7 +9174,7 @@ async function whichBinary(bin) {
   }
 }
 function spawnLogged(command, args, logPath, options = {}) {
-  const spawnFn = options.spawnFn ?? spawn6;
+  const spawnFn = options.spawnFn ?? spawn7;
   const redact = options.redact ?? [];
   const redactedError = (err) => new Error(redactSecrets(String(err), redact));
   return new Promise((resolve3, reject) => {
@@ -9141,9 +9328,9 @@ function claudeHeadlessArgs(opts) {
 async function missingClaudeAdapter(workspace, prompt) {
   const m = /^\/([A-Za-z0-9][A-Za-z0-9_-]*)/.exec(prompt.trimStart());
   if (!m?.[1]) return null;
-  const rel = path43.join(".claude", "commands", `${m[1]}.md`);
+  const rel = path44.join(".claude", "commands", `${m[1]}.md`);
   try {
-    await access9(path43.join(workspace, rel));
+    await access9(path44.join(workspace, rel));
     return null;
   } catch {
     return rel;
@@ -9259,13 +9446,13 @@ async function detectAgentBackend(requested, whichFn = whichBinary) {
 
 // src/plan-loop/run-loop.ts
 import { mkdir as mkdir6, readFile as readFile24, rm as rm2, unlink as unlink2 } from "fs/promises";
-import path47 from "path";
+import path48 from "path";
 
 // src/plan-loop/external-review.ts
-import { spawn as spawn7 } from "child_process";
-import path44 from "path";
-var CANONICAL_REL = path44.join(".cursor", "scripts", "plan-external-review.sh");
-var FALLBACK_REL = path44.join("scripts", "plan-external-review.sh");
+import { spawn as spawn8 } from "child_process";
+import path45 from "path";
+var CANONICAL_REL = path45.join(".cursor", "scripts", "plan-external-review.sh");
+var FALLBACK_REL = path45.join("scripts", "plan-external-review.sh");
 function isPlanExhaustedReason(reason) {
   const r = reason.trim().toLowerCase();
   if (!r) return false;
@@ -9283,12 +9470,12 @@ function shouldArmExternalPlanReview(input) {
   return false;
 }
 async function armExternalPlanReview(root, options = {}) {
-  const spawnFn = options.spawnFn ?? spawn7;
+  const spawnFn = options.spawnFn ?? spawn8;
   const existsFn = options.existsFn ?? fileExists;
   const log = options.log ?? ((line) => console.log(line));
   const force = options.force === true;
-  const canonicalPath = path44.join(root, CANONICAL_REL);
-  const fallbackPath = path44.join(root, FALLBACK_REL);
+  const canonicalPath = path45.join(root, CANONICAL_REL);
+  const fallbackPath = path45.join(root, FALLBACK_REL);
   let scriptPath = null;
   let scriptRel = CANONICAL_REL;
   if (await existsFn(canonicalPath)) {
@@ -9341,7 +9528,7 @@ async function armExternalPlanReview(root, options = {}) {
 }
 
 // src/plan-loop/persona-banners.ts
-import path45 from "path";
+import path46 from "path";
 import {
   blue,
   cyan as cyan4,
@@ -9377,7 +9564,7 @@ function resolveColor(name, fallback) {
 async function resolveCliPersonaId(root) {
   try {
     const cfg = await readJson(
-      path45.join(root, ".cursor", "context", "config.json")
+      path46.join(root, ".cursor", "context", "config.json")
     );
     const modes = cfg?.agentPersona?.modes ?? cfg?.workspaceSkin?.modes;
     const id = modes?.[CLI_RUN_PLAN_MODE];
@@ -9388,7 +9575,7 @@ async function resolveCliPersonaId(root) {
 }
 async function loadPersonaPack(root, personaId) {
   try {
-    const personaPath = path45.join(root, "registry", "personas", "core", personaId, "persona.json");
+    const personaPath = path46.join(root, "registry", "personas", "core", personaId, "persona.json");
     const pack = await readJson(personaPath);
     if (!pack || typeof pack.id !== "string") return null;
     return pack;
@@ -9438,7 +9625,7 @@ function createPersonaBannerPrinter(persona) {
 
 // src/plan-loop/plan-state.ts
 import { readFile as readFile22, readdir as readdir9 } from "fs/promises";
-import path46 from "path";
+import path47 from "path";
 function countPendingTodos(raw) {
   const lines = raw.split(/\r?\n/);
   let inFront = 0;
@@ -9466,7 +9653,7 @@ function countPendingTodos(raw) {
 async function findActivePlanFile(plansDir) {
   if (!await fileExists(plansDir)) return null;
   const files = (await readdir9(plansDir)).filter((f) => f.endsWith(".plan.md")).sort();
-  return files[0] ? path46.join(plansDir, files[0]) : null;
+  return files[0] ? path47.join(plansDir, files[0]) : null;
 }
 async function readPlan(planPath) {
   return readFile22(planPath, "utf8");
@@ -9569,9 +9756,9 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 async function runPlanLoop(opts) {
-  const plansDir = path47.join(opts.root, ".cursor", "plans");
-  const stopFile = path47.join(opts.root, ".cursor", "loop.stop");
-  const logDir = path47.join(opts.root, ".cursor", "loop-logs");
+  const plansDir = path48.join(opts.root, ".cursor", "plans");
+  const stopFile = path48.join(opts.root, ".cursor", "loop.stop");
+  const logDir = path48.join(opts.root, ".cursor", "loop-logs");
   const planPath = await findActivePlanFile(plansDir);
   if (!planPath) {
     logger.error("No active plan in .cursor/plans/");
@@ -9592,7 +9779,7 @@ async function runPlanLoop(opts) {
   try {
     const persona = await loadCliRunPlanPersona(opts.root);
     const banners = createPersonaBannerPrinter(persona);
-    console.log(`Active plan: ${path47.basename(planPath)}`);
+    console.log(`Active plan: ${path48.basename(planPath)}`);
     console.log(`Pending to-dos: ${await pending()} | max ticks: ${opts.maxTicks}`);
     console.log(`Backend: ${opts.backend.id}`);
     if (persona) {
@@ -9635,8 +9822,8 @@ async function runPlanLoop(opts) {
         planExhausted = true;
         break;
       }
-      const logPath = path47.join(logDir, `tick-${stamp()}.log`);
-      const relLog = path47.relative(opts.root, logPath);
+      const logPath = path48.join(logDir, `tick-${stamp()}.log`);
+      const relLog = path48.relative(opts.root, logPath);
       console.log("");
       const tickLine = `=== tick ${tick}/${opts.maxTicks} - pending: ${before} - log: ${relLog} ===`;
       if (banners) banners.tickStart(tickLine);
@@ -9727,7 +9914,7 @@ async function runPlanLoop(opts) {
     const finishDetail = `after ${tick} tick(s); pending: ${pendingNow}`;
     if (banners) banners.phaseComplete(finishDetail);
     console.log(
-      `Loop finished after ${tick} tick(s). Pending now: ${pendingNow}. Logs in ${path47.relative(opts.root, logDir)}/`
+      `Loop finished after ${tick} tick(s). Pending now: ${pendingNow}. Logs in ${path48.relative(opts.root, logDir)}/`
     );
     if (planExhausted || shouldArmExternalPlanReview({ pending: pendingNow, stopReason })) {
       await armExternalPlanReview(opts.root);
@@ -9809,7 +9996,7 @@ var runPlanCommand = defineCommand16({
       return;
     }
     const code = await runPlanLoop({
-      root: path48.resolve(args.cwd),
+      root: path49.resolve(args.cwd),
       maxTicks,
       sleepSeconds,
       model: args.model ? String(args.model) : void 0,
@@ -9822,12 +10009,12 @@ var runPlanCommand = defineCommand16({
 
 // src/commands/run.ts
 import { homedir as homedir4 } from "os";
-import path50 from "path";
+import path51 from "path";
 import { defineCommand as defineCommand17 } from "citty";
 
 // src/plan-loop/dispatch.ts
 import { mkdir as mkdir7, readFile as readFile25 } from "fs/promises";
-import path49 from "path";
+import path50 from "path";
 var RUN_CATALOG = [
   "run-plan",
   "run-plan-all",
@@ -9840,6 +10027,7 @@ var RUN_CATALOG = [
   "git-staging",
   "kit-staging"
 ];
+var FIRST_CLASS_SLASH_COMMANDS = ["run-plan", "run-plan-all"];
 var RUN_PROMOTE_BLOCKED = ["git-prod", "kit-prod"];
 function normalizeSlashName(raw) {
   return raw.replace(/^\//, "").replace(/\.md$/i, "").trim();
@@ -9851,8 +10039,26 @@ function classifySlash(name) {
   if (RUN_CATALOG.includes(n)) return "catalog";
   return "unknown";
 }
+function rewriteRootArgvToRun(argv) {
+  const idx = argv.findIndex((arg) => arg.length > 0 && !arg.startsWith("-"));
+  if (idx < 0) return argv;
+  const token = argv[idx];
+  if (!token || token === "run") return argv;
+  const kind = classifySlash(token);
+  if (kind === "unknown") return argv;
+  const slash = normalizeSlashName(token);
+  if (FIRST_CLASS_SLASH_COMMANDS.includes(slash)) {
+    if (token === slash) return argv;
+    const next2 = [...argv];
+    next2[idx] = slash;
+    return next2;
+  }
+  const next = [...argv];
+  next.splice(idx, 1, "run", slash);
+  return next;
+}
 function commandMarkdownPath(root, name) {
-  return path49.join(root, ".cursor", "commands", `${normalizeSlashName(name)}.md`);
+  return path50.join(root, ".cursor", "commands", `${normalizeSlashName(name)}.md`);
 }
 function buildDispatchPrompt(commandBody) {
   return [
@@ -9936,20 +10142,20 @@ async function runHeadlessDispatch(opts) {
   });
 }
 async function ensureDispatchLogPath(root) {
-  const logDir = path49.join(root, ".cursor", "loop-logs");
+  const logDir = path50.join(root, ".cursor", "loop-logs");
   await mkdir7(logDir, { recursive: true });
-  return path49.join(logDir, `run-${stamp2()}.log`);
+  return path50.join(logDir, `run-${stamp2()}.log`);
 }
 
 // src/commands/run.ts
 function displayPath(target, home = homedir4()) {
-  const resolvedHome = path50.resolve(home);
+  const resolvedHome = path51.resolve(home);
   if (target === resolvedHome) return "~";
-  const prefix = resolvedHome.endsWith(path50.sep) ? resolvedHome : `${resolvedHome}${path50.sep}`;
-  return target.startsWith(prefix) ? `~${path50.sep}${target.slice(prefix.length)}` : target;
+  const prefix = resolvedHome.endsWith(path51.sep) ? resolvedHome : `${resolvedHome}${path51.sep}`;
+  return target.startsWith(prefix) ? `~${path51.sep}${target.slice(prefix.length)}` : target;
 }
 async function executeRun(input) {
-  const root = path50.resolve(input.cwd);
+  const root = path51.resolve(input.cwd);
   const slash = normalizeSlashName(input.slash);
   if (!slash) {
     return { exitCode: 1, error: "Provide a slash: agent-kit run <slash>" };
@@ -9998,7 +10204,7 @@ async function executeRun(input) {
     const stdout = [
       "--dry-run: no agent will be started.",
       `Slash: ${slash}`,
-      `Command file: ${path50.relative(root, file.path)}`,
+      `Command file: ${path51.relative(root, file.path)}`,
       `Backend: ${detected.id} (${displayPath(detected.bin)})`,
       "Prompt:",
       prompt
@@ -10007,8 +10213,8 @@ async function executeRun(input) {
   }
   const logPath = await ensureDispatchLogPath(root);
   console.log(`Dispatch: ${slash} via ${detected.id}`);
-  console.log(`Command file: ${path50.relative(root, file.path)}`);
-  console.log(`Log: ${path50.relative(root, logPath)}`);
+  console.log(`Command file: ${path51.relative(root, file.path)}`);
+  console.log(`Log: ${path51.relative(root, logPath)}`);
   try {
     const result = await runHeadlessDispatch({
       backendId: detected.id,
@@ -10023,6 +10229,68 @@ async function executeRun(input) {
     return { exitCode: 1, error: String(err) };
   }
 }
+var runDispatchArgs = {
+  cwd: {
+    type: "string",
+    description: "Project root (default: current directory)",
+    default: process.cwd()
+  },
+  backend: {
+    type: "string",
+    description: `Agent CLI (${listDetectBackendIds().join(" | ")}; default: auto)`,
+    default: "auto"
+  },
+  model: {
+    type: "string",
+    description: "Optional model id passed to the agent CLI",
+    default: ""
+  },
+  "dry-run": {
+    type: "boolean",
+    description: "Print the resolved backend and prompt, then exit without starting an agent",
+    default: false
+  },
+  "max-ticks": {
+    type: "string",
+    description: "For run-plan alias only: maximum ticks (default: 10)",
+    default: "10"
+  },
+  sleep: {
+    type: "string",
+    description: "For run-plan alias only: seconds between ticks (default: 5)",
+    default: "5"
+  }
+};
+async function runSlashCli(slash, args) {
+  const maxTicks = Number.parseInt(String(args["max-ticks"]), 10);
+  const sleepSeconds = Number.parseFloat(String(args.sleep));
+  if (!Number.isFinite(maxTicks) || maxTicks < 1) {
+    logger.error("--max-ticks must be a positive integer");
+    process.exitCode = 1;
+    return;
+  }
+  if (!Number.isFinite(sleepSeconds) || sleepSeconds < 0) {
+    logger.error("--sleep must be a non-negative number");
+    process.exitCode = 1;
+    return;
+  }
+  const result = await executeRun({
+    slash,
+    cwd: String(args.cwd),
+    backend: String(args.backend),
+    model: args.model ? String(args.model) : void 0,
+    dryRun: Boolean(args["dry-run"]),
+    maxTicks,
+    sleepSeconds
+  });
+  if (result.stdout) {
+    console.log(result.stdout);
+  }
+  if (result.error) {
+    logger.error(result.error);
+  }
+  process.exitCode = result.exitCode;
+}
 var runCommand = defineCommand17({
   meta: {
     name: "run",
@@ -10031,69 +10299,23 @@ var runCommand = defineCommand17({
   args: {
     slash: {
       type: "positional",
-      description: "Slash name (e.g. backlog-add, run-plan, continue-plan)",
+      description: "Slash name (e.g. run-plan-all, backlog-add, continue-plan)",
       required: true
     },
-    cwd: {
-      type: "string",
-      description: "Project root (default: current directory)",
-      default: process.cwd()
-    },
-    backend: {
-      type: "string",
-      description: `Agent CLI (${listDetectBackendIds().join(" | ")}; default: auto)`,
-      default: "auto"
-    },
-    model: {
-      type: "string",
-      description: "Optional model id passed to the agent CLI",
-      default: ""
-    },
-    "dry-run": {
-      type: "boolean",
-      description: "Print the resolved backend and prompt, then exit without starting an agent",
-      default: false
-    },
-    "max-ticks": {
-      type: "string",
-      description: "For run-plan alias only: maximum ticks (default: 10)",
-      default: "10"
-    },
-    sleep: {
-      type: "string",
-      description: "For run-plan alias only: seconds between ticks (default: 5)",
-      default: "5"
-    }
+    ...runDispatchArgs
   },
   async run({ args }) {
-    const maxTicks = Number.parseInt(String(args["max-ticks"]), 10);
-    const sleepSeconds = Number.parseFloat(String(args.sleep));
-    if (!Number.isFinite(maxTicks) || maxTicks < 1) {
-      logger.error("--max-ticks must be a positive integer");
-      process.exitCode = 1;
-      return;
-    }
-    if (!Number.isFinite(sleepSeconds) || sleepSeconds < 0) {
-      logger.error("--sleep must be a non-negative number");
-      process.exitCode = 1;
-      return;
-    }
-    const result = await executeRun({
-      slash: String(args.slash ?? ""),
-      cwd: String(args.cwd),
-      backend: String(args.backend),
-      model: args.model ? String(args.model) : void 0,
-      dryRun: Boolean(args["dry-run"]),
-      maxTicks,
-      sleepSeconds
-    });
-    if (result.stdout) {
-      console.log(result.stdout);
-    }
-    if (result.error) {
-      logger.error(result.error);
-    }
-    process.exitCode = result.exitCode;
+    await runSlashCli(String(args.slash ?? ""), args);
+  }
+});
+var runPlanAllCommand = defineCommand17({
+  meta: {
+    name: "run-plan-all",
+    description: "Headless /run-plan-all queue from the L0 file. Numbered-list HITL. Never git-prod."
+  },
+  args: runDispatchArgs,
+  async run({ args }) {
+    await runSlashCli("run-plan-all", args);
   }
 });
 
@@ -10120,22 +10342,21 @@ var scanCommand = defineCommand18({
 });
 
 // src/commands/setup-global.ts
-import { spawn as spawn8 } from "child_process";
+import { spawn as spawn9 } from "child_process";
 import { appendFile, mkdir as mkdir8, readFile as readFile26, writeFile as writeFile13 } from "fs/promises";
 import { homedir as homedir5 } from "os";
-import path51 from "path";
+import path52 from "path";
 import { confirm as confirm2, isCancel as isCancel2 } from "@clack/prompts";
 import { defineCommand as defineCommand19 } from "citty";
 import { cyan as cyan5, green as green4, yellow as yellow3 } from "kolorist";
 var NPM_GLOBAL_DIR_NAME = ".npm-global";
 var SETUP_GLOBAL_MARKER = "# agent-kit setup-global";
-var DEFAULT_PACKAGE_SPEC = "@dadado/agent-kit-cli";
 function planSetupGlobalSteps(env, options = {}) {
   const homeDir = options.homeDir ?? homedir5();
-  const packageSpec = options.packageSpec ?? DEFAULT_PACKAGE_SPEC;
-  const npmGlobalDir = path51.join(homeDir, NPM_GLOBAL_DIR_NAME);
-  const npmGlobalBin = path51.join(npmGlobalDir, "bin");
-  const npmrcPath = path51.join(homeDir, ".npmrc");
+  const packageSpec = options.packageSpec ?? pinnedCliSpec();
+  const npmGlobalDir = path52.join(homeDir, NPM_GLOBAL_DIR_NAME);
+  const npmGlobalBin = path52.join(npmGlobalDir, "bin");
+  const npmrcPath = path52.join(homeDir, ".npmrc");
   const npmrcPrefixValue = `~/${NPM_GLOBAL_DIR_NAME}`;
   const pathExportLine = `export PATH="${npmGlobalBin}:$PATH"`;
   const shellProfile = env.shellProfile;
@@ -10215,7 +10436,7 @@ async function safeReadFile(fs, filePath) {
   }
 }
 var defaultNpmInstallImpl = (packageSpec) => new Promise((resolve3) => {
-  const child = spawn8("npm", ["i", "-g", packageSpec], { stdio: "inherit" });
+  const child = spawn9("npm", ["i", "-g", packageSpec], { stdio: "inherit" });
   child.on("error", (error) => resolve3({ ok: false, error }));
   child.on("close", (code) => {
     if (code === 0) resolve3({ ok: true });
@@ -10266,11 +10487,48 @@ async function runSetupGlobal(options = {}) {
   const homeDir = options.homeDir ?? homedir5();
   const env = await assessEnvironmentImpl(options);
   const plan = planSetupGlobalSteps(env, { homeDir, packageSpec: options.packageSpec });
-  if (plan.alreadyWritable) {
+  if (plan.alreadyWritable && pathCliStatus(env, KIT_VERSION) === "current") {
     printHeader(env, print);
-    print(green4("npm's global prefix is already writable \u2014 nothing to fix."));
+    print(green4("npm's global prefix is writable and PATH `agent-kit` matches this CLI."));
     return { exitCode: 0, mutated: false, outcome: "already-ok", env, plan };
   }
+  if (plan.alreadyWritable) {
+    printHeader(env, print);
+    print(
+      `PATH \`agent-kit\` is ${env.binVersion ? `v${env.binVersion}` : "missing or unreadable"}; this CLI is v${KIT_VERSION}.`
+    );
+    print(`Prefix is writable. Next step is only: npm i -g ${plan.packageSpec}`);
+    if (options.dryRun) {
+      print("Dry run: no changes.");
+      print(`  npm i -g ${plan.packageSpec}`);
+      return { exitCode: 0, mutated: false, outcome: "dry-run", env, plan };
+    }
+    const nonInteractiveWritable = options.nonInteractive ?? isNonInteractive();
+    if (nonInteractiveWritable) {
+      print("No changes made. Run this yourself:");
+      print(`  npm i -g ${plan.packageSpec}`);
+      print("  hash -r");
+      print("  agent-kit --version");
+      return { exitCode: 0, mutated: false, outcome: "manual-instructions", env, plan };
+    }
+    const confirmStep2 = options.confirmImpl ?? defaultConfirmImpl;
+    const npmInstall2 = options.npmInstallImpl ?? defaultNpmInstallImpl;
+    const proceedInstall2 = await confirmStep2(`Run: npm i -g ${plan.packageSpec}?`);
+    if (!proceedInstall2) {
+      print(yellow3("Cancelled: no changes made."));
+      return { exitCode: 1, mutated: false, outcome: "cancelled", env, plan };
+    }
+    const installResult2 = await npmInstall2(plan.packageSpec);
+    if (!installResult2.ok) {
+      const hint = classifyInstallError(installResult2.error);
+      print(`  npm install failed: ${hint.message}`);
+      print(hint.recovery);
+      return { exitCode: 1, mutated: false, outcome: "error", env, plan };
+    }
+    print(green4(`  done: ${plan.packageSpec} installed globally.`));
+    print("  If this shell still shows the old version: hash -r (or open a new terminal).");
+    return { exitCode: 0, mutated: true, outcome: "completed", env, plan };
+  }
   if (options.dryRun) {
     printHeader(env, print);
     print("Dry run \u2014 no changes will be made. Steps that would run:");
@@ -10397,7 +10655,7 @@ var setupGlobalCommand = defineCommand19({
 });
 
 // src/commands/status.ts
-import path52 from "path";
+import path53 from "path";
 import { defineCommand as defineCommand20 } from "citty";
 function profileStatus(profile) {
   if (!profile) return { origin: "none", evidence: [], profile: null };
@@ -10428,13 +10686,14 @@ var statusCommand = defineCommand20({
     }
   },
   async run({ args }) {
-    const rootDir = path52.resolve(args.cwd);
-    const [manifest, rawProfile, scan] = await Promise.all([
+    const rootDir = path53.resolve(args.cwd);
+    const [manifest, rawProfile, scan, env] = await Promise.all([
       loadAgentKitManifest(rootDir),
       readJson(
-        path52.join(rootDir, ".cursor", "agent-kit.config.json")
+        path53.join(rootDir, ".cursor", "agent-kit.config.json")
       ),
-      runScanner(rootDir)
+      runScanner(rootDir),
+      assessEnvironment()
     ]);
     const readiness = createReadinessReport(scan, { generatorVersion: KIT_VERSION });
     const profile = profileStatus(rawProfile);
@@ -10470,6 +10729,17 @@ var statusCommand = defineCommand20({
         `  registry:   ${manifest.registry?.url ?? "(default)"} @ ${manifest.registry?.ref ?? "(default)"}`
       );
       if (manifest.installedAt) console.log(`  installed at: ${manifest.installedAt}`);
+      if (manifest.version !== KIT_VERSION) {
+        console.log(
+          `  overlay:    this CLI is v${KIT_VERSION}; apply with the same binary, not a stale PATH hit:`
+        );
+        console.log(`              ${npxPinned(KIT_VERSION, "update")}`);
+      }
+      const pathStatus = pathCliStatus(env, KIT_VERSION);
+      if (pathStatus === "behind" || pathStatus === "unknown") {
+        console.log(`  PATH bin:   v${env.binVersion ?? "unknown"} at ${env.binPath}`);
+        console.log("              bare `agent-kit update` will re-stamp that older version");
+      }
     }
     console.log("Repository readiness");
     console.log(
@@ -10656,6 +10926,8 @@ ${err.recovery}
       logApplyStats(stats);
       const transition = next.version === existing.version ? `unchanged at v${next.version}` : `v${existing.version} \u2192 v${next.version}`;
       logger.success(`Update complete: ${transition} (L3 protected paths left untouched).`);
+      const sync = await syncPathCliToRuntime({ runtimeVersion: KIT_VERSION });
+      for (const line of sync.lines) console.log(line);
     } finally {
       await registry.unlock?.();
     }
@@ -10664,7 +10936,7 @@ ${err.recovery}
 
 // src/commands/validate.ts
 import { readFile as readFile27 } from "fs/promises";
-import path53 from "path";
+import path54 from "path";
 import { defineCommand as defineCommand22 } from "citty";
 
 // src/invariants/plan-schema.ts
@@ -10711,7 +10983,7 @@ function validatePlanFrontmatterText(text) {
 // src/commands/validate.ts
 async function resolveEditedPath(cwd, explicit) {
   if (explicit) {
-    const filePath2 = path53.resolve(cwd, explicit);
+    const filePath2 = path54.resolve(cwd, explicit);
     try {
       return { filePath: filePath2, content: await readFile27(filePath2, "utf8") };
     } catch {
@@ -10721,7 +10993,7 @@ async function resolveEditedPath(cwd, explicit) {
   const payload = await readStdinJson();
   const rel = typeof payload.file_path === "string" && payload.file_path || typeof payload.path === "string" && payload.path || typeof payload.file === "string" && payload.file || "";
   if (!rel) return null;
-  const filePath = path53.isAbsolute(rel) ? rel : path53.resolve(cwd, rel);
+  const filePath = path54.isAbsolute(rel) ? rel : path54.resolve(cwd, rel);
   try {
     return { filePath, content: await readFile27(filePath, "utf8") };
   } catch {
@@ -10751,7 +11023,7 @@ var validateCommand = defineCommand22({
       async run({ args }) {
         const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
         const fileArg = typeof args.file === "string" ? args.file : void 0;
-        const filePath = fileArg ? path53.resolve(cwd, fileArg) : path53.join(path53.resolve(cwd), ".cursor", "HANDOFF.md");
+        const filePath = fileArg ? path54.resolve(cwd, fileArg) : path54.join(path54.resolve(cwd), ".cursor", "HANDOFF.md");
         let content = "";
         try {
           content = await readFile27(filePath, "utf8");
@@ -10778,7 +11050,7 @@ var validateCommand = defineCommand22({
           process.exitCode = 2;
           return;
         }
-        const filePath = path53.resolve(cwd, fileArg);
+        const filePath = path54.resolve(cwd, fileArg);
         let content = "";
         try {
           content = await readFile27(filePath, "utf8");
@@ -10800,7 +11072,7 @@ var validateCommand = defineCommand22({
       },
       async run({ args }) {
         const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
-        const resolved = await resolveEditedPath(path53.resolve(cwd));
+        const resolved = await resolveEditedPath(path54.resolve(cwd));
         if (!resolved) {
           console.log(JSON.stringify({}));
           return;
@@ -10913,7 +11185,7 @@ function renderWelcomeScreen(opts = {}) {
     })(),
     "",
     muted2(
-      "Chat HITL (start-project, git-staging/prod, run-plan-all) stays in Cursor slash commands."
+      "Terminal: agent-kit run-plan-all (same as agent-kit run run-plan-all). Cursor chat: /run-plan-all."
     ),
     muted2(
       `${shouldUseVisualMotion(opts) ? SPACE_MARKS.star : SPACE_MARKS.tick} ${tipAt(
@@ -10938,7 +11210,7 @@ var CLI_HELP_GROUPS = [
   {
     id: "mission",
     title: "MISSION",
-    commands: ["handoff", "plan-index", "run", "run-plan"]
+    commands: ["handoff", "plan-index", "run", "run-plan", "run-plan-all"]
   },
   {
     id: "dashboard",
@@ -11004,7 +11276,7 @@ async function renderGroupedRootHelp(cmd) {
   lines.push(
     g(`Use \`${name} <command> --help\` for more information about a command.`),
     g(
-      "Ask questions is Cursor-only. Use `agent-kit run <slash>` for headless numbered-list HITL. `/git-prod` stays operator-gated."
+      "Ask questions is Cursor-only. Use `agent-kit run-plan-all` or `agent-kit run <slash>` for headless numbered-list HITL. `/git-prod` stays operator-gated."
     ),
     g(`${tipMark} ${tip}`),
     ""
@@ -11013,6 +11285,9 @@ async function renderGroupedRootHelp(cmd) {
 }
 
 // src/index.ts
+var rewrittenArgv = rewriteRootArgvToRun(process.argv.slice(2));
+process.argv.length = 2;
+process.argv.push(...rewrittenArgv);
 var main = defineCommand23({
   meta: {
     name: "agent-kit",
@@ -11035,6 +11310,7 @@ var main = defineCommand23({
     "plan-index": planIndexCommand,
     run: runCommand,
     "run-plan": runPlanCommand,
+    "run-plan-all": runPlanAllCommand,
     dashboard: dashboardCommand,
     "dashboard-broadcast": dashboardBroadcastCommand,
     "mission-control": missionControlCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dadado/agent-kit-cli",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "description": "Agent Kit CLI: HITL framework install and tooling for AI-assisted IDEs (rules, skills, plan/handoff, context).",
   "license": "PolyForm-Noncommercial-1.0.0",
   "type": "module",