bmad-method 6.3.1-next.9 → 6.4.0

package/tools/installer/modules/custom-module-manager.js

@@ -4,6 +4,13 @@ const path = require('node:path');
 const { execSync } = require('node:child_process');
 const prompts = require('../prompts');
 
+function quoteCustomRef(ref) {
+  if (typeof ref !== 'string' || !/^[\w.\-+/]+$/.test(ref)) {
+    throw new Error(`Unsafe ref name: ${JSON.stringify(ref)}`);
+  }
+  return `"${ref}"`;
+}
+
 /**
  * Manages custom modules installed from user-provided sources.
  * Supports any Git host (GitHub, GitLab, Bitbucket, self-hosted) and local file paths.
@@ -38,8 +45,8 @@ class CustomModuleManager {
       };
     }
 
-    const trimmed = input.trim();
-    if (!trimmed) {
+    const trimmedRaw = input.trim();
+    if (!trimmedRaw) {
       return {
         type: null,
         cloneUrl: null,
@@ -52,8 +59,53 @@ class CustomModuleManager {
       };
     }
 
+    // Extract optional @<tag-or-branch> suffix from the end of the input.
+    // Semver-valid characters: letters, digits, dot, hyphen, underscore, plus, slash.
+    // Raw commit SHAs are NOT supported here — `git clone --branch` can't take
+    // them; use --pin at the module level or check out the SHA manually.
+    // Only strip when the tail looks like a ref, so we don't disturb
+    // URLs without a version spec or the SSH protocol's `git@host:...` prefix.
+    let trimmed = trimmedRaw;
+    let versionSuffix = null;
+    const lastAt = trimmedRaw.lastIndexOf('@');
+    // Skip if @ is part of git@github.com:... (first char cannot be stripped as version)
+    // and skip if @ appears before the path rather than after a ref-shaped tail.
+    if (lastAt > 0) {
+      const candidate = trimmedRaw.slice(lastAt + 1);
+      const before = trimmedRaw.slice(0, lastAt);
+      // candidate must be ref-shaped and must not itself look like a URL / SSH host
+      if (/^[\w.\-+/]+$/.test(candidate) && !candidate.includes(':')) {
+        // Avoid consuming the @ in `git@host:owner/repo` — `before` wouldn't end with a path separator
+        // in that case. Require that the @ comes after the host/path, not inside the auth segment.
+        // Rule: the @ is a version suffix only if `before` looks like a complete URL or local path.
+        const beforeLooksLikeRepo =
+          before.startsWith('/') ||
+          before.startsWith('./') ||
+          before.startsWith('../') ||
+          before.startsWith('~') ||
+          /^https?:\/\//i.test(before) ||
+          /^git@[^:]+:.+/.test(before);
+        if (beforeLooksLikeRepo) {
+          versionSuffix = candidate;
+          trimmed = before;
+        }
+      }
+    }
+
     // Local path detection: starts with /, ./, ../, or ~
     if (trimmed.startsWith('/') || trimmed.startsWith('./') || trimmed.startsWith('../') || trimmed.startsWith('~')) {
+      if (versionSuffix) {
+        return {
+          type: 'local',
+          cloneUrl: null,
+          subdir: null,
+          localPath: null,
+          cacheKey: null,
+          displayName: null,
+          isValid: false,
+          error: 'Local paths do not support @version suffixes',
+        };
+      }
       return this._parseLocalPath(trimmed);
     }
 
@@ -66,6 +118,8 @@ class CustomModuleManager {
         cloneUrl: trimmed,
         subdir: null,
         localPath: null,
+        version: versionSuffix || null,
+        rawInput: trimmedRaw,
         cacheKey: `${host}/${owner}/${repo}`,
         displayName: `${owner}/${repo}`,
         isValid: true,
@@ -79,29 +133,47 @@ class CustomModuleManager {
       const [, host, owner, repo, remainder] = httpsMatch;
       const cloneUrl = `https://${host}/${owner}/${repo}`;
       let subdir = null;
+      let urlRef = null; // branch/tag extracted from /tree/<ref>/subdir
 
       if (remainder) {
         // Extract subdir from deep path patterns used by various Git hosts
         const deepPathPatterns = [
-          /^\/(?:-\/)?tree\/[^/]+\/(.+)$/, // GitHub /tree/branch/path, GitLab /-/tree/branch/path
-          /^\/(?:-\/)?blob\/[^/]+\/(.+)$/, // /blob/branch/path (treat same as tree)
-          /^\/src\/[^/]+\/(.+)$/, // Gitea/Forgejo /src/branch/path
+          { regex: /^\/(?:-\/)?tree\/([^/]+)\/(.+)$/, refIdx: 1, pathIdx: 2 }, // GitHub, GitLab
+          { regex: /^\/(?:-\/)?blob\/([^/]+)\/(.+)$/, refIdx: 1, pathIdx: 2 },
+          { regex: /^\/src\/([^/]+)\/(.+)$/, refIdx: 1, pathIdx: 2 }, // Gitea/Forgejo
         ];
+        // Also match `/tree/<ref>` with no subdir
+        const refOnlyPatterns = [/^\/(?:-\/)?tree\/([^/]+?)\/?$/, /^\/(?:-\/)?blob\/([^/]+?)\/?$/, /^\/src\/([^/]+?)\/?$/];
 
-        for (const pattern of deepPathPatterns) {
-          const match = remainder.match(pattern);
+        for (const p of deepPathPatterns) {
+          const match = remainder.match(p.regex);
           if (match) {
-            subdir = match[1].replace(/\/$/, ''); // strip trailing slash
+            urlRef = match[p.refIdx];
+            subdir = match[p.pathIdx].replace(/\/$/, '');
             break;
           }
         }
+        if (!subdir) {
+          for (const r of refOnlyPatterns) {
+            const match = remainder.match(r);
+            if (match) {
+              urlRef = match[1];
+              break;
+            }
+          }
+        }
       }
 
+      // Precedence: explicit @version suffix > URL /tree/<ref> path segment.
+      const version = versionSuffix || urlRef || null;
+
       return {
         type: 'url',
         cloneUrl,
         subdir,
         localPath: null,
+        version,
+        rawInput: trimmedRaw,
         cacheKey: `${host}/${owner}/${repo}`,
         displayName: `${owner}/${repo}`,
         isValid: true,
@@ -255,6 +327,10 @@ class CustomModuleManager {
     const silent = options.silent || false;
     const displayName = parsed.displayName;
 
+    // Pin override: --pin CODE=TAG resolved at module-selection time overrides
+    // any @version suffix present in the URL.
+    const effectiveVersion = options.pinOverride || parsed.version || null;
+
     await fs.ensureDir(path.dirname(repoCacheDir));
 
     const createSpinner = async () => {
@@ -264,8 +340,23 @@ class CustomModuleManager {
       return await prompts.spinner();
     };
 
+    // If an existing cache exists but was cloned at a different version, re-clone.
+    // Tracked via .bmad-source.json's recorded version.
     if (await fs.pathExists(repoCacheDir)) {
-      // Update existing clone
+      let cachedVersion = null;
+      try {
+        const existing = await fs.readJson(path.join(repoCacheDir, '.bmad-source.json'));
+        cachedVersion = existing?.version || null;
+      } catch {
+        // no metadata; treat as mismatched to be safe if a version was requested
+      }
+      if ((effectiveVersion || null) !== (cachedVersion || null)) {
+        await fs.remove(repoCacheDir);
+      }
+    }
+
+    if (await fs.pathExists(repoCacheDir)) {
+      // Update existing clone (same version as before)
       const fetchSpinner = await createSpinner();
       fetchSpinner.start(`Updating ${displayName}...`);
       try {
@@ -274,10 +365,25 @@ class CustomModuleManager {
           stdio: ['ignore', 'pipe', 'pipe'],
           env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
         });
-        execSync('git reset --hard origin/HEAD', {
-          cwd: repoCacheDir,
-          stdio: ['ignore', 'pipe', 'pipe'],
-        });
+        if (effectiveVersion) {
+          // Fetch the ref as either a tag or a branch — `origin <ref>` works
+          // for both, whereas `origin tag <ref>` fails for branch refs parsed
+          // out of /tree/<branch>/... URLs.
+          execSync(`git fetch --depth 1 origin ${quoteCustomRef(effectiveVersion)} --no-tags`, {
+            cwd: repoCacheDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+          });
+          execSync(`git checkout --quiet FETCH_HEAD`, {
+            cwd: repoCacheDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          });
+        } else {
+          execSync('git reset --hard origin/HEAD', {
+            cwd: repoCacheDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          });
+        }
         fetchSpinner.stop(`Updated ${displayName}`);
       } catch {
         fetchSpinner.error(`Update failed, re-downloading ${displayName}`);
@@ -287,25 +393,44 @@ class CustomModuleManager {
 
     if (!(await fs.pathExists(repoCacheDir))) {
       const fetchSpinner = await createSpinner();
-      fetchSpinner.start(`Cloning ${displayName}...`);
+      fetchSpinner.start(`Cloning ${displayName}${effectiveVersion ? ` @ ${effectiveVersion}` : ''}...`);
       try {
-        execSync(`git clone --depth 1 "${parsed.cloneUrl}" "${repoCacheDir}"`, {
-          stdio: ['ignore', 'pipe', 'pipe'],
-          env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
-        });
+        if (effectiveVersion) {
+          execSync(`git clone --depth 1 --branch ${quoteCustomRef(effectiveVersion)} "${parsed.cloneUrl}" "${repoCacheDir}"`, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+          });
+        } else {
+          execSync(`git clone --depth 1 "${parsed.cloneUrl}" "${repoCacheDir}"`, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+          });
+        }
         fetchSpinner.stop(`Cloned ${displayName}`);
       } catch (error_) {
         fetchSpinner.error(`Failed to clone ${displayName}`);
-        throw new Error(`Failed to clone ${parsed.cloneUrl}: ${error_.message}`);
+        const refSuffix = effectiveVersion ? `@${effectiveVersion}` : '';
+        throw new Error(`Failed to clone ${parsed.cloneUrl}${refSuffix}: ${error_.message}`);
       }
     }
 
+    // Record the resolved SHA for the manifest writer.
+    let resolvedSha = null;
+    try {
+      resolvedSha = execSync('git rev-parse HEAD', { cwd: repoCacheDir, stdio: 'pipe' }).toString().trim();
+    } catch {
+      // swallow — a non-git repo (local path) wouldn't reach here anyway
+    }
+
     // Write source metadata for later URL reconstruction
     const metadataPath = path.join(repoCacheDir, '.bmad-source.json');
     await fs.writeJson(metadataPath, {
       cloneUrl: parsed.cloneUrl,
       cacheKey: parsed.cacheKey,
       displayName: parsed.displayName,
+      version: effectiveVersion || null,
+      rawInput: parsed.rawInput || sourceInput,
+      sha: resolvedSha,
       clonedAt: new Date().toISOString(),
     });
 
@@ -346,10 +471,26 @@ class CustomModuleManager {
     const resolver = new PluginResolver();
     const resolved = await resolver.resolve(repoPath, plugin);
 
+    // Read clone metadata (written by cloneRepo) so we can pick up the
+    // resolved git ref + SHA for manifest recording.
+    let cloneMetadata = null;
+    if (sourceUrl) {
+      try {
+        cloneMetadata = await fs.readJson(path.join(repoPath, '.bmad-source.json'));
+      } catch {
+        // no metadata — local-source or legacy cache
+      }
+    }
+
     // Stamp source info onto each resolved module for manifest tracking
     for (const mod of resolved) {
       if (sourceUrl) mod.repoUrl = sourceUrl;
       if (localPath) mod.localPath = localPath;
+      if (cloneMetadata) {
+        mod.cloneRef = cloneMetadata.version || null;
+        mod.cloneSha = cloneMetadata.sha || null;
+        mod.rawInput = cloneMetadata.rawInput || null;
+      }
       CustomModuleManager._resolutionCache.set(mod.code, mod);
     }
 

package/tools/installer/modules/external-manager.js

@@ -5,8 +5,50 @@ const { execSync } = require('node:child_process');
 const yaml = require('yaml');
 const prompts = require('../prompts');
 const { RegistryClient } = require('./registry-client');
+const { resolveChannel, tagExists, parseGitHubRepo } = require('./channel-resolver');
+const { decideChannelForModule } = require('./channel-plan');
 
-const REGISTRY_RAW_URL = 'https://raw.githubusercontent.com/bmad-code-org/bmad-plugins-marketplace/main/registry/official.yaml';
+const VALID_CHANNELS = new Set(['stable', 'next', 'pinned']);
+
+function normalizeChannelName(raw) {
+  if (typeof raw !== 'string') return null;
+  const lower = raw.trim().toLowerCase();
+  return VALID_CHANNELS.has(lower) ? lower : null;
+}
+
+/**
+ * Conservative quoting for tag names passed to git commands. Tags are
+ * user-typed (--pin) or come from the GitHub API. Only allow the semver
+ * character class we use to tag BMad releases; anything else throws.
+ */
+function quoteShell(ref) {
+  if (typeof ref !== 'string' || !/^[\w.\-+/]+$/.test(ref)) {
+    throw new Error(`Unsafe ref name: ${JSON.stringify(ref)}`);
+  }
+  return `"${ref}"`;
+}
+
+async function readChannelMarker(markerPath) {
+  try {
+    if (!(await fs.pathExists(markerPath))) return null;
+    const content = await fs.readFile(markerPath, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+async function writeChannelMarker(markerPath, data) {
+  try {
+    await fs.writeFile(markerPath, JSON.stringify({ ...data, writtenAt: new Date().toISOString() }, null, 2));
+  } catch {
+    // Best-effort: marker is an optimization, not a correctness requirement.
+  }
+}
+
+const MARKETPLACE_OWNER = 'bmad-code-org';
+const MARKETPLACE_REPO = 'bmad-plugins-marketplace';
+const MARKETPLACE_REF = 'main';
 const FALLBACK_CONFIG_PATH = path.join(__dirname, 'registry-fallback.yaml');
 
 /**
@@ -17,10 +59,25 @@ const FALLBACK_CONFIG_PATH = path.join(__dirname, 'registry-fallback.yaml');
  * @class ExternalModuleManager
  */
 class ExternalModuleManager {
+  // moduleCode → { channel, version, ref, sha, repoUrl, resolvedFallback }
+  // Populated when cloneExternalModule resolves a channel. Shared across all
+  // instances so the manifest writer (which often instantiates a fresh
+  // ExternalModuleManager) sees resolutions made during install.
+  static _resolutions = new Map();
+
   constructor() {
     this._client = new RegistryClient();
   }
 
+  /**
+   * Get the most recent channel resolution for a module (if any).
+   * @param {string} moduleCode
+   * @returns {Object|null}
+   */
+  getResolution(moduleCode) {
+    return ExternalModuleManager._resolutions.get(moduleCode) || null;
+  }
+
   /**
    * Load the official modules registry from GitHub, falling back to the
    * bundled YAML file if the fetch fails.
@@ -33,8 +90,7 @@ class ExternalModuleManager {
 
     // Try remote registry first
     try {
-      const content = await this._client.fetch(REGISTRY_RAW_URL);
-      const config = yaml.parse(content);
+      const config = await this._client.fetchGitHubYaml(MARKETPLACE_OWNER, MARKETPLACE_REPO, 'registry/official.yaml', MARKETPLACE_REF);
       if (config?.modules?.length) {
         this.cachedModules = config;
         return config;
@@ -74,6 +130,7 @@ class ExternalModuleManager {
       defaultSelected: mod.default_selected === true || mod.defaultSelected === true,
       type: mod.type || 'bmad-org',
       npmPackage: mod.npm_package || mod.npmPackage || null,
+      defaultChannel: normalizeChannelName(mod.default_channel || mod.defaultChannel) || 'stable',
       builtIn: mod.built_in === true,
       isExternal: mod.built_in !== true,
     };
@@ -119,10 +176,15 @@ class ExternalModuleManager {
   }
 
   /**
-   * Clone an external module repository to cache
+   * Clone an external module repository to cache, resolving the requested
+   * channel (stable / next / pinned) to a concrete git ref.
+   *
    * @param {string} moduleCode - Code of the external module
    * @param {Object} options - Clone options
-   * @param {boolean} options.silent - Suppress spinner output
+   * @param {boolean} [options.silent] - Suppress spinner output
+   * @param {Object} [options.channelOptions] - Parsed channel flags. See
+   *   modules/channel-plan.js. When absent, the module installs on its
+   *   registry-declared default channel (typically 'stable').
    * @returns {string} Path to the cloned repository
    */
   async cloneExternalModule(moduleCode, options = {}) {
@@ -160,38 +222,160 @@ class ExternalModuleManager {
       return await prompts.spinner();
     };
 
-    // Track if we need to install dependencies
+    // ─── Resolve channel plan ─────────────────────────────────────────────
+    // Post-install callers (config generation, directory setup, help catalog
+    // rebuild) invoke findModuleSource/cloneExternalModule without
+    // channelOptions just to locate the module's files. Those calls must not
+    // redecide the channel — the install step already chose one, cloned the
+    // right ref, and recorded a resolution. If we re-resolve without flags,
+    // we'd snap back to stable and overwrite a pinned install.
+    const hasExplicitChannelInput =
+      options.channelOptions &&
+      (options.channelOptions.global ||
+        (options.channelOptions.nextSet && options.channelOptions.nextSet.size > 0) ||
+        (options.channelOptions.pins && options.channelOptions.pins.size > 0));
+    const existingResolution = ExternalModuleManager._resolutions.get(moduleCode);
+    const haveUsableCache = await fs.pathExists(moduleCacheDir);
+
+    if (!hasExplicitChannelInput && existingResolution && haveUsableCache) {
+      // This is a look-up only; the module is already installed at its chosen
+      // ref. Skip cloning and return the cached path unchanged.
+      return moduleCacheDir;
+    }
+
+    const planEntry = decideChannelForModule({
+      code: moduleCode,
+      channelOptions: options.channelOptions,
+      registryDefault: moduleInfo.defaultChannel,
+    });
+
+    // Same-plan short-circuit: a single install calls cloneExternalModule
+    // several times (config collection, directory setup, help-catalog rebuild)
+    // with the same channelOptions. The first call resolves + clones; later
+    // calls with an identical plan and a valid cache should return immediately
+    // instead of re-running resolveChannel() and `git fetch` (slow; can fail
+    // on flaky networks even though the tagCache dedupes the GitHub API hit).
+    if (existingResolution && haveUsableCache && existingResolution.channel === planEntry.channel) {
+      const samePin = planEntry.channel !== 'pinned' || existingResolution.version === planEntry.pin;
+      if (samePin) return moduleCacheDir;
+    }
+
+    let resolved;
+    try {
+      resolved = await resolveChannel({
+        channel: planEntry.channel,
+        pin: planEntry.pin,
+        repoUrl: moduleInfo.url,
+      });
+    } catch (error) {
+      // Tag-API failure (rate limit, transient network). If we already have
+      // a usable cache at a recorded ref, treat this as "couldn't check for
+      // updates" and re-use the cached version silently — that's the right
+      // call for an update/quick-update, since the semantics don't change
+      // and the user isn't worse off than before they ran this command.
+      const cachedMarker = await readChannelMarker(path.join(moduleCacheDir, '.bmad-channel.json'));
+      if (cachedMarker?.channel && (await fs.pathExists(moduleCacheDir))) {
+        if (!silent) {
+          await prompts.log.warn(
+            `Could not check for updates to ${moduleInfo.name} (${error.message}); using cached ${cachedMarker.version || cachedMarker.channel}.`,
+          );
+        }
+        ExternalModuleManager._resolutions.set(moduleCode, {
+          channel: cachedMarker.channel,
+          version: cachedMarker.version || 'main',
+          ref: cachedMarker.version && cachedMarker.version !== 'main' ? cachedMarker.version : null,
+          sha: cachedMarker.sha,
+          repoUrl: moduleInfo.url,
+          resolvedFallback: false,
+          planSource: 'cached',
+        });
+        return moduleCacheDir;
+      }
+      // No cache to fall back on — this is effectively a fresh install with
+      // no offline safety net. Surface a clear error with actionable guidance.
+      const isRateLimited = /rate limit/i.test(error.message);
+      const hint = isRateLimited
+        ? process.env.GITHUB_TOKEN
+          ? 'Your GITHUB_TOKEN may have expired or been rate-limited on its own budget. Try a different token or wait for the reset.'
+          : 'Set a GITHUB_TOKEN env var (any personal access token with public-repo read) to raise the 60-req/hour anonymous limit.'
+        : `Check your network connection, or rerun with \`--next=${moduleCode}\` / \`--pin ${moduleCode}=<tag>\` to skip the tag lookup.`;
+      throw new Error(`Could not resolve stable tag for '${moduleCode}' (${error.message}). ${hint}`);
+    }
+
+    if (resolved.resolvedFallback && !silent) {
+      if (resolved.reason === 'no-stable-tags') {
+        await prompts.log.warn(`No stable releases found for ${moduleInfo.name}; installing from main.`);
+      } else if (resolved.reason === 'not-a-github-url') {
+        await prompts.log.warn(`Cannot determine stable tags for ${moduleInfo.name} (non-GitHub URL); installing from main.`);
+      }
+    }
+
+    // Validate pin before we burn time cloning. Best-effort: skip on non-GitHub URLs.
+    if (planEntry.channel === 'pinned') {
+      const parsed = parseGitHubRepo(moduleInfo.url);
+      if (parsed) {
+        try {
+          const exists = await tagExists(parsed.owner, parsed.repo, planEntry.pin);
+          if (!exists) {
+            throw new Error(`Tag '${planEntry.pin}' not found in ${parsed.owner}/${parsed.repo}.`);
+          }
+        } catch (error) {
+          if (error.message?.includes('not found')) throw error;
+          // Network hiccup on tag verification — let the clone attempt fail clearly.
+        }
+      }
+    }
+
+    // ─── Clone or update cache by resolved channel ────────────────────────
+    const markerPath = path.join(moduleCacheDir, '.bmad-channel.json');
+    const currentMarker = await readChannelMarker(markerPath);
+    const needsChannelReset = currentMarker && currentMarker.channel !== resolved.channel;
+
     let needsDependencyInstall = false;
     let wasNewClone = false;
 
-    // Check if already cloned
+    if (needsChannelReset && (await fs.pathExists(moduleCacheDir))) {
+      // Channel changed (e.g. user switched stable→next). Blow away and re-clone
+      // to avoid tangling shallow clones of different refs.
+      await fs.remove(moduleCacheDir);
+    }
+
     if (await fs.pathExists(moduleCacheDir)) {
-      // Try to update if it's a git repo
+      // Cache exists on the right channel. Refresh the ref.
       const fetchSpinner = await createSpinner();
       fetchSpinner.start(`Fetching ${moduleInfo.name}...`);
       try {
-        const currentRef = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
-        // Fetch and reset to remote - works better with shallow clones than pull
-        execSync('git fetch origin --depth 1', {
-          cwd: moduleCacheDir,
-          stdio: ['ignore', 'pipe', 'pipe'],
-          env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
-        });
-        execSync('git reset --hard origin/HEAD', {
-          cwd: moduleCacheDir,
-          stdio: ['ignore', 'pipe', 'pipe'],
-          env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
-        });
-        const newRef = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
+        const currentSha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
 
-        fetchSpinner.stop(`Fetched ${moduleInfo.name}`);
-        // Force dependency install if we got new code
-        if (currentRef !== newRef) {
-          needsDependencyInstall = true;
+        if (resolved.channel === 'next') {
+          execSync('git fetch origin --depth 1', {
+            cwd: moduleCacheDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+          });
+          execSync('git reset --hard origin/HEAD', {
+            cwd: moduleCacheDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+          });
+        } else {
+          // stable or pinned — fetch the specific tag and check it out.
+          execSync(`git fetch --depth 1 origin tag ${quoteShell(resolved.ref)} --no-tags`, {
+            cwd: moduleCacheDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+          });
+          execSync(`git checkout --quiet FETCH_HEAD`, {
+            cwd: moduleCacheDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          });
         }
+
+        const newSha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
+        fetchSpinner.stop(`Fetched ${moduleInfo.name}`);
+        if (currentSha !== newSha) needsDependencyInstall = true;
       } catch {
         fetchSpinner.error(`Fetch failed, re-downloading ${moduleInfo.name}`);
-        // If update fails, remove and re-clone
         await fs.remove(moduleCacheDir);
         wasNewClone = true;
       }
@@ -199,22 +383,41 @@ class ExternalModuleManager {
       wasNewClone = true;
     }
 
-    // Clone if not exists or was removed
     if (wasNewClone) {
       const fetchSpinner = await createSpinner();
       fetchSpinner.start(`Fetching ${moduleInfo.name}...`);
       try {
-        execSync(`git clone --depth 1 "${moduleInfo.url}" "${moduleCacheDir}"`, {
-          stdio: ['ignore', 'pipe', 'pipe'],
-          env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
-        });
+        if (resolved.channel === 'next') {
+          execSync(`git clone --depth 1 "${moduleInfo.url}" "${moduleCacheDir}"`, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+          });
+        } else {
+          execSync(`git clone --depth 1 --branch ${quoteShell(resolved.ref)} "${moduleInfo.url}" "${moduleCacheDir}"`, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+          });
+        }
         fetchSpinner.stop(`Fetched ${moduleInfo.name}`);
       } catch (error) {
         fetchSpinner.error(`Failed to fetch ${moduleInfo.name}`);
-        throw new Error(`Failed to clone external module '${moduleCode}': ${error.message}`);
+        throw new Error(`Failed to clone external module '${moduleCode}' at ${resolved.version}: ${error.message}`);
       }
     }
 
+    // Record resolution (channel + tag + SHA) for the manifest writer to pick up.
+    const sha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
+    ExternalModuleManager._resolutions.set(moduleCode, {
+      channel: resolved.channel,
+      version: resolved.version,
+      ref: resolved.ref,
+      sha,
+      repoUrl: moduleInfo.url,
+      resolvedFallback: !!resolved.resolvedFallback,
+      planSource: planEntry.source,
+    });
+    await writeChannelMarker(markerPath, { channel: resolved.channel, version: resolved.version, sha });
+
     // Install dependencies if package.json exists
     const packageJsonPath = path.join(moduleCacheDir, 'package.json');
     const nodeModulesPath = path.join(moduleCacheDir, 'node_modules');