akm-cli 0.10.261019 → 0.10.261021

package/dist/commands/sources/plugin-upgrade.js

@@ -14,11 +14,14 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { IS_WINDOWS, parseJsonc } from "../../core/common.js";
+import { UsageError } from "../../core/errors.js";
 import { moveToTrash } from "../../core/trash.js";
 import { OPENCODE_V1, OPENCODE_V2, readPackageVersion, } from "../../integrations/harnesses/opencode/plugin-layout.js";
 import { opencodeCacheDir, opencodeConfigDir } from "../../integrations/harnesses/opencode/roots.js";
 import { detectOpencodeMajor, OPENCODE_BIN, resolveOpencodeBin } from "../../integrations/harnesses/opencode/version.js";
+import { isExactSemver, isPrerelease } from "../../registry/semver.js";
 import { semverOrder } from "../../runtime.js";
+import { ChannelWriteError, claudeChannelEdits, codexChannelEdit, codexMarketplace, editChannelJson, writeChannelEdits, } from "./plugin-channels.js";
 const MARKETPLACE = "akm-plugins";
 const PLUGIN_ID = `akm@${MARKETPLACE}`;
 const READ_TIMEOUT_MS = 30_000;
@@ -60,6 +63,13 @@ function skipped(harness, message) {
 function failed(harness, message) {
     return { harness, outcome: "failed", message };
 }
+function channelWriteFailure(harness, error, before) {
+    return {
+        ...failed(harness, String(error)),
+        channel: error instanceof ChannelWriteError && error.writtenFiles.length ? "unknown" : before,
+        ...(error instanceof ChannelWriteError ? { backups: error.backups } : {}),
+    };
+}
 /** An entry for a refresh that ran: `updated` when the installed version moved, else `current`. */
 function refreshed(harness, from, to) {
     const moved = from !== undefined && to !== undefined && from !== to;
@@ -74,48 +84,88 @@ function unknownRefresh(harness, from) {
         message: "checking needs a fetch of the akm-plugins marketplace, which --check does not do; `akm upgrade` refreshes it",
     };
 }
-function claudePluginVersion() {
+function claudePlugins() {
     const listed = runCommand("claude", ["plugin", "list", "--json"], READ_TIMEOUT_MS);
     if (!listed.ok)
         return { error: listed };
     const plugins = parseJson(listed.stdout);
-    const plugin = Array.isArray(plugins) ? plugins.find((p) => p?.id === PLUGIN_ID) : undefined;
-    return { version: plugin ? String(plugin.version ?? "") : undefined };
+    const installations = Array.isArray(plugins)
+        ? plugins
+            .filter((p) => p?.id === PLUGIN_ID)
+            .map((p) => ({
+            version: typeof p.version === "string" ? p.version : undefined,
+            scope: typeof p.scope === "string" ? p.scope : undefined,
+            projectPath: typeof p.projectPath === "string" ? p.projectPath : undefined,
+        }))
+        : [];
+    return { installations };
 }
-function detectClaudeCode() {
+function detectClaudeCode(strict = false) {
     const marketplaces = runCommand("claude", ["plugin", "marketplace", "list", "--json"], READ_TIMEOUT_MS);
     if (!marketplaces.ok) {
-        return { entry: skipped("claude-code", marketplaces.missing ? "claude is not on PATH" : marketplaces.error) };
+        const configDir = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
+        const pluginsRoot = process.env.AKM_CLAUDE_PLUGINS_DIR ?? process.env.CLAUDE_CODE_PLUGIN_CACHE_DIR ?? path.join(configDir, "plugins");
+        const configured = fs.existsSync(path.join(pluginsRoot, "known_marketplaces.json"));
+        return {
+            entry: strict && (!marketplaces.missing || configured)
+                ? { ...failed("claude-code", marketplaces.error), channel: "unknown" }
+                : skipped("claude-code", marketplaces.missing ? "claude is not on PATH" : marketplaces.error),
+        };
     }
     const list = parseJson(marketplaces.stdout);
     const marketplace = Array.isArray(list) ? list.find((m) => m?.name === MARKETPLACE) : undefined;
     if (!marketplace)
         return { entry: skipped("claude-code", `the ${MARKETPLACE} marketplace is not configured`) };
-    const plugin = claudePluginVersion();
+    const plugin = claudePlugins();
     if ("error" in plugin)
-        return { entry: skipped("claude-code", plugin.error.error) };
-    if (plugin.version === undefined)
+        return {
+            entry: strict
+                ? { ...failed("claude-code", plugin.error.error), channel: "unknown" }
+                : skipped("claude-code", plugin.error.error),
+        };
+    if (!plugin.installations.length)
         return { entry: skipped("claude-code", "the akm plugin is not installed") };
-    return { version: plugin.version, ref: typeof marketplace.ref === "string" ? marketplace.ref : undefined };
+    return {
+        version: plugin.installations[0]?.version,
+        installations: plugin.installations,
+        ref: typeof marketplace.ref === "string" ? marketplace.ref : undefined,
+    };
 }
-function upgradeClaudeCode(dryRun, next) {
-    const detected = detectClaudeCode();
+function upgradeClaudeCode(dryRun, next, channel) {
+    const detected = detectClaudeCode(channel !== undefined);
     if ("entry" in detected)
         return detected.entry;
-    const entry = refreshClaudeCode(dryRun, detected.version);
-    return next ? withChannelNote(entry, detected.ref, "re-add the marketplace as `itlackey/akm-plugins@next`") : entry;
+    const before = refChannel(detected.ref);
+    let backups = [];
+    if (channel && !dryRun) {
+        try {
+            const configDir = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
+            const pluginsRoot = process.env.AKM_CLAUDE_PLUGINS_DIR ??
+                process.env.CLAUDE_CODE_PLUGIN_CACHE_DIR ??
+                path.join(configDir, "plugins");
+            backups = writeChannelEdits(claudeChannelEdits(configDir, pluginsRoot, channel, detected.installations.flatMap((p) => (p.projectPath ? [p.projectPath] : []))));
+        }
+        catch (error) {
+            return channelWriteFailure("claude-code", error, before);
+        }
+    }
+    const entry = refreshClaudeCode(dryRun, detected.version, channel ? detected.installations : undefined);
+    const noted = next && !channel ? withChannelNote(entry, detected.ref) : entry;
+    return channelResult(noted, before, channel, dryRun, backups);
 }
-function refreshClaudeCode(dryRun, from) {
+function refreshClaudeCode(dryRun, from, installations) {
     if (dryRun)
         return unknownRefresh("claude-code", from);
     const marketplace = runCommand("claude", ["plugin", "marketplace", "update", MARKETPLACE], REFRESH_TIMEOUT_MS);
     if (!marketplace.ok)
         return failed("claude-code", marketplace.error);
-    const update = runCommand("claude", ["plugin", "update", PLUGIN_ID], REFRESH_TIMEOUT_MS);
-    if (!update.ok)
-        return failed("claude-code", update.error);
-    const after = claudePluginVersion();
-    return refreshed("claude-code", from, "version" in after ? after.version : undefined);
+    for (const installation of installations ?? [{}]) {
+        const update = runCommand("claude", ["plugin", "update", PLUGIN_ID, ...(installation.scope ? ["--scope", installation.scope] : [])], REFRESH_TIMEOUT_MS, { cwd: installation.projectPath });
+        if (!update.ok)
+            return failed("claude-code", update.error);
+    }
+    const after = claudePlugins();
+    return refreshed("claude-code", from, "installations" in after ? after.installations[0]?.version : undefined);
 }
 // ── Codex ───────────────────────────────────────────────────────────────────
 function codexPluginVersion() {
@@ -126,29 +176,39 @@ function codexPluginVersion() {
     const plugin = parsed?.installed?.find((p) => p?.pluginId === PLUGIN_ID);
     return { version: plugin ? String(plugin.version ?? "") : undefined };
 }
-/** The ref `[marketplaces.akm-plugins]` follows in Codex's config.toml; undefined when it names none (the default branch). */
+function codexConfigFile() {
+    return path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "config.toml");
+}
 function codexMarketplaceRef() {
     try {
-        const home = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
-        const config = fs.readFileSync(path.join(home, "config.toml"), "utf8");
-        const section = config.split(/^\[/m).find((part) => part.startsWith(`marketplaces.${MARKETPLACE}]`));
-        return section?.match(/^ref\s*=\s*"([^"]+)"/m)?.[1];
+        const ref = codexMarketplace(codexConfigFile())?.ref;
+        return typeof ref === "string" ? ref : undefined;
     }
     catch {
         return undefined;
     }
 }
-function upgradeCodex(dryRun, next) {
+function upgradeCodex(dryRun, next, channel) {
     const before = codexPluginVersion();
     if ("error" in before)
-        return skipped("codex", before.error.missing ? "codex is not on PATH" : before.error.error);
+        return channel && (!before.error.missing || fs.existsSync(codexConfigFile()))
+            ? { ...failed("codex", before.error.error), channel: "unknown" }
+            : skipped("codex", before.error.missing ? "codex is not on PATH" : before.error.error);
     if (before.version === undefined) {
         return skipped("codex", `the akm plugin is not installed from the ${MARKETPLACE} marketplace`);
     }
+    const previous = refChannel(codexMarketplaceRef());
+    const backups = [];
+    if (channel && previous !== channel && !dryRun) {
+        try {
+            backups.push(...writeChannelEdits([codexChannelEdit(codexConfigFile(), channel)]));
+        }
+        catch (error) {
+            return channelWriteFailure("codex", error, previous);
+        }
+    }
     const entry = refreshCodex(dryRun, before.version);
-    return next
-        ? withChannelNote(entry, codexMarketplaceRef(), "run `codex plugin marketplace add itlackey/akm-plugins --ref next`")
-        : entry;
+    return channelResult(next && !channel ? withChannelNote(entry, codexMarketplaceRef()) : entry, previous, channel, dryRun, backups);
 }
 function refreshCodex(dryRun, from) {
     if (dryRun)
@@ -192,10 +252,10 @@ export function openCodeConfigSpec(flavor) {
                 const entries = config[key];
                 if (!Array.isArray(entries))
                     continue;
-                for (const entry of entries) {
+                for (const [index, entry] of entries.entries()) {
                     const spec = entrySpec(entry);
                     if (spec !== undefined && namesPackage(spec, flavor.pkg))
-                        return { spec, key };
+                        return { spec, key, file, jsonPath: [key, index, ...(Array.isArray(entry) ? [0] : [])] };
                 }
             }
         }
@@ -317,7 +377,7 @@ function upgradeOpenCode(dryRun, target) {
         return failed(harness, latest.error);
     if (target.notFollowingNext)
         return skipped(harness, notFollowingNext(flavor));
-    if (cache.version === latest.version)
+    if (!target.switchChannel && cache.version === latest.version)
         return { harness, outcome: "current", from: cache.version, to: latest.version };
     const base = { harness, from: cache.version, to: latest.version };
     // OpenCode 1's refresh replaces the cache the running OpenCode is using, so it waits for the exit.
@@ -350,12 +410,27 @@ function upgradeOpenCode(dryRun, target) {
         return skipped(harness, `\`${bin}\` on PATH is ${major === undefined ? "of an unknown version" : `OpenCode ${major}`}, ` +
             `not OpenCode ${flavor.major}, so it cannot refresh the ${flavor.pkg} cache; the cache is left alone`);
     }
-    if (flavor.replacesCache) {
+    let backups = [];
+    if (target.switchChannel) {
+        const configured = openCodeConfigSpec(flavor);
+        if (!configured)
+            return failed(harness, "the configured plugin entry disappeared before switching its channel");
+        try {
+            backups = writeChannelEdits([editChannelJson(configured.file, configured.jsonPath, target.spec)]);
+        }
+        catch (error) {
+            return channelWriteFailure(harness, error, target.currentChannel ?? "unknown");
+        }
+    }
+    if (flavor.replacesCache && fs.existsSync(cache.dir)) {
         try {
             moveToTrash(cache.dir);
         }
         catch (error) {
-            return failed(harness, `could not move ${cache.dir} to the trash: ${error instanceof Error ? error.message : String(error)}`);
+            return {
+                ...failed(harness, `could not move ${cache.dir} to the trash: ${error instanceof Error ? error.message : String(error)}`),
+                backups,
+            };
         }
     }
     const trashed = flavor.replacesCache ? " (the old cache is in the trash)" : "";
@@ -369,36 +444,64 @@ function upgradeOpenCode(dryRun, target) {
             refresh = runCommand(bin, flavor.refresh(target.spec), PREFETCH_TIMEOUT_MS, { cwd: workDir });
         }
         if (!refresh.ok)
-            return failed(harness, `${refresh.error}${trashed}`);
+            return { ...failed(harness, `${refresh.error}${trashed}`), backups };
     }
     finally {
         fs.rmSync(workDir, { recursive: true, force: true });
     }
     const after = detectOpenCodeCache(tag, flavor);
     if (!after)
-        return failed(harness, `opencode did not re-create the plugin cache${trashed}`);
-    return { ...base, outcome: "updated", to: after.version ?? latest.version };
+        return { ...failed(harness, `opencode did not re-create the plugin cache${trashed}`), backups };
+    return { ...base, outcome: "updated", to: after.version ?? latest.version, ...(backups.length ? { backups } : {}) };
 }
 // ── Orchestration ───────────────────────────────────────────────────────────
 /**
  * The note `--next` adds to a marketplace harness. The channel is the ref the marketplace follows (`next` is the
- * prerelease branch, the default branch is stable); akm only updates that ref and cannot switch it.
+ * prerelease branch, the default branch is stable); only an explicit --channel switches it.
  */
-function withChannelNote(entry, ref, howToSwitch) {
+function refChannel(ref) {
+    return !ref || ref === "main" || ref === "master" ? "latest" : ref === "next" ? "next" : "pinned";
+}
+function channelResult(entry, before, target, dryRun, backups = []) {
+    const changed = target !== undefined && target !== before;
+    return {
+        ...entry,
+        channel: changed && !dryRun ? target : before,
+        ...(target ? { targetChannel: target } : {}),
+        ...(changed
+            ? {
+                previousChannel: before,
+                message: `${entry.message ? `${entry.message}; ` : ""}${dryRun ? "would configure" : "configured"} channel ${before} → ${target}`,
+            }
+            : {}),
+        ...(backups.length ? { backups } : {}),
+    };
+}
+function withChannelNote(entry, ref) {
     if (entry.outcome === "skipped")
         return entry;
     const note = ref === "next"
         ? `--next: the ${MARKETPLACE} marketplace follows ref next, the prerelease channel`
-        : `--next: the ${MARKETPLACE} marketplace follows ${ref ? `ref ${ref}` : "the default branch (stable)"}, ` +
-            `not the prerelease channel; akm upgrade cannot switch it, ${howToSwitch} to follow prereleases`;
+        : `--next: the ${MARKETPLACE} marketplace follows ${ref ? `ref ${ref}` : "the default branch (stable)"}; use akm upgrade --channel next to switch all installed plugins`;
     return { ...entry, message: entry.message ? `${entry.message}; ${note}` : note };
 }
 export function upgradePlugins(opts) {
     return [
-        upgradeClaudeCode(opts.dryRun, opts.next),
-        upgradeCodex(opts.dryRun, opts.next),
-        ...opts.openCode.map((target) => upgradeOpenCode(opts.dryRun, target)),
-    ];
+        upgradeClaudeCode(opts.dryRun, opts.next, opts.channel),
+        upgradeCodex(opts.dryRun, opts.next, opts.channel),
+        ...opts.openCode.map((target) => {
+            const entry = upgradeOpenCode(opts.dryRun, target);
+            if (target.currentChannel === undefined)
+                return entry;
+            const changed = entry.channel === undefined &&
+                target.switchChannel &&
+                ((entry.backups?.length ?? 0) > 0 || entry.outcome === "updated" || entry.outcome === "current");
+            return channelResult(entry, entry.channel ?? target.currentChannel ?? "unknown", opts.dryRun || changed ? target.switchChannel : undefined, opts.dryRun, entry.backups);
+        }),
+    ].map((entry) => ({
+        ...entry,
+        ...(entry.channel && opts.currentChannel ? { channelMismatch: entry.channel !== opts.currentChannel } : {}),
+    }));
 }
 /**
  * When an OpenCode plugin is present the CLI target is the akm-cli that
@@ -469,10 +572,32 @@ function lockstepSource(targets) {
  * naming any other spec (an exact version, or `@next` on a plain run) is left
  * alone, with no lockstep.
  */
-function resolveOpenCodeTarget(next, flavor, configured) {
+function resolveOpenCodeTarget(next, flavor, configured, channel) {
     // OpenCode 1 with no config entry behaves like a bare one: it would resolve @latest. OpenCode 2's
     // re-fetch writes the config, so its plugin is only refreshed where the config already names it.
-    const spec = configured?.spec ?? flavor.pkg;
+    const currentSpec = configured?.spec ?? flavor.pkg;
+    const currentChannel = currentSpec === flavor.pkg || currentSpec === `${flavor.pkg}@latest`
+        ? "latest"
+        : currentSpec === nextSpec(flavor)
+            ? "next"
+            : "pinned";
+    const spec = channel && configured ? (channel === "next" ? nextSpec(flavor) : flavor.pkg) : currentSpec;
+    if (channel && configured) {
+        const fromSpec = currentSpec === flavor.pkg ? `${flavor.pkg}@latest` : currentSpec;
+        const oldDir = path.join(opencodeCacheDir(), flavor.cacheFolder(fromSpec));
+        const oldModules = flavor.nodeModulesDir(oldDir);
+        const version = oldModules ? readPackageVersion(path.join(oldModules, flavor.pkg, "package.json")) : undefined;
+        return {
+            flavor,
+            spec,
+            tag: channel,
+            currentChannel,
+            notFollowingNext: false,
+            switchChannel: currentChannel !== channel ? channel : undefined,
+            cache: { dir: path.join(opencodeCacheDir(), flavor.cacheFolder(`${flavor.pkg}@${channel}`)), version },
+            latest: lookupOpenCodeLatest(channel, flavor),
+        };
+    }
     const leftAlone = (skip) => ({
         flavor,
         cache: undefined,
@@ -480,6 +605,7 @@ function resolveOpenCodeTarget(next, flavor, configured) {
         tag: next ? "next" : "latest",
         spec,
         notFollowingNext: false,
+        currentChannel: configured ? currentChannel : undefined,
         skip,
     });
     if (flavor.globalConfigOnly) {
@@ -499,45 +625,201 @@ function resolveOpenCodeTarget(next, flavor, configured) {
     const tag = followNext ? "next" : "latest";
     const cache = detectOpenCodeCache(tag, flavor);
     const latest = cache ? lookupOpenCodeLatest(tag, flavor) : undefined;
-    return { flavor, cache, latest, tag, spec, notFollowingNext: next && !followNext };
+    return {
+        flavor,
+        cache,
+        latest,
+        tag,
+        spec,
+        currentChannel: configured || cache ? currentChannel : undefined,
+        notFollowingNext: next && !followNext,
+    };
 }
 /**
  * The OpenCode plugins this host has: OpenCode 1's always, OpenCode 2's only when the global config
  * names `akm-opencode-v2` or OpenCode 2 has cached it, so a host with just OpenCode 1 sees the same
  * output as before.
  */
-function resolveOpenCodeTargets(next) {
-    const targets = [resolveOpenCodeTarget(next, OPENCODE_V1, openCodeConfigSpec(OPENCODE_V1))];
+function resolveOpenCodeTargets(next, channel) {
+    const targets = [resolveOpenCodeTarget(next, OPENCODE_V1, openCodeConfigSpec(OPENCODE_V1), channel)];
     const v2 = openCodeConfigSpec(OPENCODE_V2);
     if (v2 || openCodeV2Cached())
-        targets.push(resolveOpenCodeTarget(next, OPENCODE_V2, v2));
+        targets.push(resolveOpenCodeTarget(next, OPENCODE_V2, v2, channel));
     return targets;
 }
+/** Inspect the requested branch in a disposable clone before changing any installation. */
+function marketplaceTargetVersion(source, channel, harness) {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "akm-channel-check-"));
+    const checkout = path.join(root, "marketplace");
+    try {
+        const cloned = runCommand("git", [
+            "clone",
+            "--depth",
+            "1",
+            "--single-branch",
+            ...(channel === "next" ? ["--branch", "next"] : []),
+            "--",
+            source,
+            checkout,
+        ], REFRESH_TIMEOUT_MS);
+        if (!cloned.ok)
+            throw new UsageError(`Could not check the target plugin version: ${cloned.error}`);
+        const catalog = parseJson(fs.readFileSync(path.join(checkout, ...(harness === "codex" ? [".agents", "plugins"] : [".claude-plugin"]), "marketplace.json"), "utf8"));
+        const plugin = catalog?.plugins?.find((p) => p.name === "akm");
+        const relative = typeof plugin?.source === "string"
+            ? plugin.source
+            : plugin?.source?.source === "local"
+                ? plugin.source.path
+                : undefined;
+        const local = relative ? path.resolve(checkout, relative) : undefined;
+        const contained = local === checkout || local?.startsWith(`${checkout}${path.sep}`);
+        const version = plugin?.version ??
+            (local && contained
+                ? readPackageVersion(path.join(local, harness === "codex" ? ".codex-plugin" : ".claude-plugin", "plugin.json"))
+                : undefined);
+        if (!version || !isExactSemver(version))
+            throw new UsageError("Could not determine the requested marketplace's akm plugin version; no channel was changed");
+        return version;
+    }
+    finally {
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+}
+function preflightMarketplaceChannels(channel, allowDowngrade) {
+    const versions = new Map();
+    const verify = (harness, source, installed) => {
+        if (allowDowngrade)
+            return;
+        const key = `${harness}:${source}`;
+        let target = versions.get(key);
+        if (!target) {
+            target = marketplaceTargetVersion(source, channel, harness);
+            versions.set(key, target);
+        }
+        if (installed && semverOrder(target, installed) < 0)
+            throw new UsageError(`Switching to ${channel} would downgrade ${harness} from ${installed} to ${target}; repeat with --allow-downgrade`);
+    };
+    const claude = detectClaudeCode(true);
+    if ("entry" in claude && claude.entry.outcome === "failed")
+        throw new UsageError(`Could not inventory Claude before switching channels: ${claude.entry.message}`);
+    if (!("entry" in claude)) {
+        const configDir = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
+        const pluginsRoot = process.env.AKM_CLAUDE_PLUGINS_DIR ?? process.env.CLAUDE_CODE_PLUGIN_CACHE_DIR ?? path.join(configDir, "plugins");
+        claudeChannelEdits(configDir, pluginsRoot, channel, claude.installations.flatMap((p) => (p.projectPath ? [p.projectPath] : [])));
+        const known = parseJson(fs.readFileSync(path.join(pluginsRoot, "known_marketplaces.json"), "utf8"));
+        const source = known[MARKETPLACE]?.source;
+        const url = source?.source === "github" && source.repo ? `https://github.com/${source.repo}.git` : source?.url;
+        if (!url)
+            throw new UsageError("Could not determine the Claude marketplace Git source; no channel was changed");
+        for (const installed of claude.installations)
+            verify("claude", url, installed.version);
+    }
+    const codex = codexPluginVersion();
+    if ("error" in codex && (!codex.error.missing || fs.existsSync(codexConfigFile())))
+        throw new UsageError(`Could not inventory Codex before switching channels: ${codex.error.error}`);
+    if (!("error" in codex) && codex.version !== undefined) {
+        codexChannelEdit(codexConfigFile(), channel);
+        const source = codexMarketplace(codexConfigFile())?.source;
+        if (typeof source !== "string")
+            throw new UsageError("Could not determine the Codex marketplace Git source; no channel was changed");
+        verify("codex", source, codex.version);
+    }
+}
 /** `akm upgrade`: the CLI step (held to the OpenCode plugin's akm), then the plugins. */
 export async function runUpgrade(args, currentVersion, deps) {
-    const next = args.next === true;
+    if (args.channel !== undefined && args.channel !== "latest" && args.channel !== "next")
+        throw new UsageError("--channel must be latest or next");
+    if (args.next && args.channel === "latest")
+        throw new UsageError("--next conflicts with --channel latest");
+    if (args.allowDowngrade && !args.channel)
+        throw new UsageError("--allow-downgrade requires --channel latest or next");
+    const switchChannel = args.channel;
+    const next = switchChannel ? switchChannel === "next" : args.next === true;
     const channel = next ? "next" : "latest";
-    const openCode = resolveOpenCodeTargets(next);
+    const currentChannel = isPrerelease(currentVersion) ? "next" : "latest";
+    const openCode = resolveOpenCodeTargets(next, switchChannel);
     const held = lockstepSource(openCode);
     const check = {
-        ...applyLockstep(await deps.checkForUpdate(currentVersion, channel), held?.latest, held?.tag ?? "latest", held?.flavor.pkg ?? OPENCODE_V1.pkg),
+        ...applyLockstep(await deps.checkForUpdate(currentVersion, channel, switchChannel !== undefined), held?.latest, held?.tag ?? "latest", held?.flavor.pkg ?? OPENCODE_V1.pkg),
         channel,
+        currentChannel,
+        ...(switchChannel ? { targetChannel: switchChannel } : {}),
     };
+    if (switchChannel &&
+        held?.latest &&
+        !("error" in held.latest) &&
+        held.latest.akmCli &&
+        semverOrder(held.latest.akmCli, check.latestVersion) < 0) {
+        check.latestVersion = held.latest.akmCli;
+        check.updateAvailable = semverOrder(currentVersion, check.latestVersion) < 0;
+    }
     if (args.check) {
-        return { mode: "check", result: { ...check, plugins: upgradePlugins({ dryRun: true, next, openCode }) } };
+        return {
+            mode: "check",
+            result: {
+                ...check,
+                plugins: upgradePlugins({ dryRun: true, next, openCode, channel: switchChannel, currentChannel }),
+            },
+        };
+    }
+    if (switchChannel && !args.allowDowngrade) {
+        if (semverOrder(check.latestVersion, currentVersion) < 0)
+            throw new UsageError(`Switching to ${channel} would downgrade akm from ${currentVersion} to ${check.latestVersion}; repeat with --allow-downgrade`);
+        for (const target of openCode) {
+            if (target.cache?.version &&
+                target.latest &&
+                !("error" in target.latest) &&
+                semverOrder(target.latest.version, target.cache.version) < 0)
+                throw new UsageError(`Switching to ${channel} would downgrade ${target.flavor.pkg} from ${target.cache.version} to ${target.latest.version}; repeat with --allow-downgrade`);
+        }
     }
+    if (switchChannel)
+        preflightMarketplaceChannels(switchChannel, args.allowDowngrade === true);
+    if (switchChannel && args.allowDowngrade && check.latestVersion !== currentVersion)
+        check.updateAvailable = true;
     const upgraded = await deps.performUpgrade(check, {
         force: args.force,
         skipPostUpgrade: args.skipPostUpgrade,
         // A package manager install must name the version, or `@latest` goes past the pin
         // (or past the prerelease that `--next` chose).
-        ...(check.lockstep?.heldBack || (next && check.latestVersion) ? { targetVersion: check.latestVersion } : {}),
+        ...(switchChannel || check.lockstep?.heldBack || (next && check.latestVersion)
+            ? { targetVersion: check.latestVersion }
+            : {}),
     });
-    const plugins = upgradePlugins({ dryRun: false, next, openCode });
-    const result = { ...upgraded, channel, ...(check.lockstep ? { lockstep: check.lockstep } : {}), plugins };
+    if (switchChannel &&
+        (upgraded.migration?.status === "blocked" ||
+            upgraded.migration?.status === "failed" ||
+            (check.latestVersion !== currentVersion && !upgraded.upgraded))) {
+        return {
+            mode: "upgrade",
+            result: { ...upgraded, channel, currentChannel, targetChannel: switchChannel, plugins: [] },
+            failed: true,
+        };
+    }
+    const plugins = upgradePlugins({
+        dryRun: false,
+        next,
+        openCode,
+        channel: switchChannel,
+        currentChannel: upgraded.upgraded ? (isPrerelease(upgraded.newVersion) ? "next" : "latest") : currentChannel,
+    });
+    const result = {
+        ...upgraded,
+        channel,
+        currentChannel,
+        ...(switchChannel ? { targetChannel: switchChannel } : {}),
+        ...(check.lockstep ? { lockstep: check.lockstep } : {}),
+        plugins,
+    };
     // The install may have succeeded, but an upgrade whose migration is
     // blocked or could not run is not done, and neither is one whose plugin
     // step failed.
     const migrationFailed = upgraded.migration?.status === "blocked" || upgraded.migration?.status === "failed";
-    return { mode: "upgrade", result, failed: migrationFailed || plugins.some((p) => p.outcome === "failed") };
+    const switchIncomplete = switchChannel !== undefined &&
+        plugins.some((p) => p.channel !== undefined && (p.channel !== switchChannel || p.outcome === "deferred" || p.outcome === "skipped"));
+    return {
+        mode: "upgrade",
+        result,
+        failed: migrationFailed || switchIncomplete || plugins.some((p) => p.outcome === "failed"),
+    };
 }

package/dist/commands/sources/self-update.js

@@ -187,11 +187,12 @@ async function lookupNextVersion(fetchOptions) {
 /**
  * The newest release. With `channel: "next"` that includes prereleases: the
  * `next` dist-tag when it is newer than the latest stable release, else the
- * stable release (a prerelease older than a stable one is never a target).
+ * stable release. An explicit channel switch sets exactChannel to select the
+ * actual next tag, leaving downgrade consent to runUpgrade.
  * A binary install downloads the GitHub release tagged `v<version>`, which a
  * prerelease has too, so the version is all the install step needs.
  */
-export async function checkForUpdate(currentVersion, fetchOptions, channel = "latest") {
+export async function checkForUpdate(currentVersion, fetchOptions, channel = "latest", exactChannel = false) {
     const installMethod = detectInstallMethod();
     const url = `https://api.github.com/repos/${REPO}/releases/latest`;
     const response = await fetchWithRetry(url, { headers: githubHeaders() }, fetchOptions);
@@ -203,7 +204,9 @@ export async function checkForUpdate(currentVersion, fetchOptions, channel = "la
     let latestVersion = latestTag.replace(/^v/, "");
     if (channel === "next") {
         const next = await lookupNextVersion(fetchOptions);
-        if (next && (latestVersion === "" || semverOrder(latestVersion, next) < 0))
+        if (exactChannel && !next)
+            throw new Error("No next prerelease is published; no channel was changed");
+        if (next && (exactChannel || latestVersion === "" || semverOrder(latestVersion, next) < 0))
             latestVersion = next;
     }
     return {

package/dist/commands/sources/source-add.js

@@ -219,7 +219,9 @@ async function addRegistryStash(ref, stashDir, explicitName, writable, position
         : [];
     const synced = await syncFromRef(ref, {
         writable: effectiveWritable,
-        ...(effectiveWritable && priorLock?.localRoot ? { writableRoot: priorLock.localRoot } : {}),
+        // Reuse a checkout only when the install is already writable; promoting a
+        // read-only snapshot (#1296) materializes a fresh checkout instead.
+        ...(existingWritable && priorLock?.localRoot ? { writableRoot: priorLock.localRoot } : {}),
         ...(requiredRoots.length > 0 ? { writableRequiredRoots: requiredRoots } : {}),
         ...(credentialRef
             ? { credential: resolveSecret(credentialRef, storeSecretResolver.resolveSecret) }
@@ -253,8 +255,10 @@ async function addRegistryStash(ref, stashDir, explicitName, writable, position
         localRoot: synced.contentDir,
         installedAt: synced.syncedAt,
     });
-    // Clean up the old materialized root on re-install (moved cache).
-    if (!effectiveWritable && priorLocalRoot && path.resolve(priorLocalRoot) !== path.resolve(synced.contentDir)) {
+    // Clean up the old materialized root on re-install (moved cache). A writable
+    // checkout may hold local work and is never removed; a read-only snapshot
+    // (including one just promoted to writable, #1296) is.
+    if (!existingWritable && priorLocalRoot && path.resolve(priorLocalRoot) !== path.resolve(synced.contentDir)) {
         try {
             fs.rmSync(priorLocalRoot, { recursive: true, force: true });
         }

package/dist/commands/sources/sources-cli.js

@@ -52,6 +52,12 @@ export const upgradeCommand = defineJsonCommand({
             description: "Skip the post-upgrade index rebuild",
             default: false,
         },
+        channel: { type: "string", description: "Switch akm and every installed harness plugin to latest or next" },
+        "allow-downgrade": {
+            type: "boolean",
+            description: "Allow an explicit channel switch to install an older release",
+            default: false,
+        },
         next: {
             type: "boolean",
             description: "Install the newest prerelease (the @next npm tag) of akm and, if OpenCode's config names akm-opencode@next, of its plugin",
@@ -59,8 +65,15 @@ export const upgradeCommand = defineJsonCommand({
         },
     },
     async run({ args }) {
-        const run = await runUpgrade({ check: args.check, force: args.force, skipPostUpgrade: args["skip-post-upgrade"], next: args.next }, pkgVersion, {
-            checkForUpdate: (version, channel) => checkForUpdate(version, undefined, channel),
+        const run = await runUpgrade({
+            check: args.check,
+            force: args.force,
+            skipPostUpgrade: args["skip-post-upgrade"],
+            next: args.next,
+            channel: args.channel,
+            allowDowngrade: args["allow-downgrade"],
+        }, pkgVersion, {
+            checkForUpdate: (version, channel, exactChannel) => checkForUpdate(version, undefined, channel, exactChannel),
             performUpgrade: (check, opts) => performUpgrade(check, opts),
         });
         if (run.mode === "check") {