@pi-unipi/updater 3.0.0-alpha.4 → 3.0.0-alpha.40

package/README.md

@@ -1,77 +1,75 @@
-# @pi-unipi/updater
+# Updater
 
-Checks npm for new versions on session start, shows a changelog diff, and lets you update with one keypress. Also provides TUI browsers for package READMEs and the changelog.
+Updater tells you when a new UniPi release is on npm and installs it with one key.
 
-The update overlay appears automatically when a newer version is found. Press `Y` to update, `n` to skip. Skipped versions are cached — you only get re-prompted when an even newer version appears.
+`@pi-unipi/updater` · part of [UniPi](../../README.md)
 
-## Commands
+## What it does
 
-| Command | Description |
-|---------|-------------|
-| `/unipi:readme [package]` | Browse package README files in TUI overlay |
-| `/unipi:changelog` | Browse CHANGELOG.md with version list and detail view |
-| `/unipi:settings` | Configure check interval and auto-update mode (Updater group) |
+- Checks the npm registry for `@pi-unipi/unipi` at session start.
+- Shows an update overlay with the changelog entries between your version and the new version.
+- Runs `pi install npm:@pi-unipi/unipi` when you press `Y`.
+- Remembers a version that you skip. It asks again only for a newer version.
+- Opens package READMEs and the changelog in TUI overlays.
+- Adds an Updater group to the info screen: installed version, latest version, status and last check.
 
-### TUI Controls
+## Quick start
 
-| Key | Action |
-|-----|--------|
-| `j/k` or Up/Down | Navigate |
-| `Enter` | Select/open |
-| `q/Esc` | Back/close |
-| `g/G` | Jump to top/bottom |
-| `Space` | Cycle options (settings) |
-| `h/l` or Left/Right | Cycle options (settings) |
+Updater ships in `@pi-unipi/unipi`. It checks the version of `@pi-unipi/unipi`, so it is useful only with the full suite.
 
-## Special Triggers
+1. Start a pi session. Updater checks npm in the background.
+2. If a newer version is on npm, the update overlay opens.
+3. Press `Y` to install. Press `n` to skip this version.
+4. Restart pi to load the new version.
 
-On session start, updater checks the npm registry for `@pi-unipi/unipi`. If a newer version exists and wasn't previously skipped, it shows the update overlay with changelog diff. This runs once per session, respecting the check interval config.
+## Commands
 
-Updater registers with the info-screen dashboard, showing installed version, latest version, update status, and last check time.
+| Command | What it does |
+|---|---|
+| `/unipi:readme [package]` | Opens the README browser. A package name, for example `utility`, opens that README. |
+| `/unipi:changelog` | Opens the changelog browser with a version list and a detail view. |
 
-## How Updates Work
+## Keys
 
-1. Session start triggers npm registry check
-2. Compare latest version with installed version
-3. If newer and not skipped, show update overlay
-4. User views changelog diff, presses `Y` to update or `n` to skip
-5. Update runs `pi install npm:@pi-unipi/unipi`
-6. Skipped version cached — re-prompted only for newer versions
+Update overlay:
 
-## Configurables
+| Key | What it does |
+|---|---|
+| `Y` or `y` | Installs the new version. |
+| `n`, `q` or `Esc` | Skips this version. |
+| `j` / `k` or arrows | Scrolls the changelog. |
+| `g` / `G` | Goes to the top or the bottom. |
 
-Config stored at `~/.unipi/config/updater/config.json`:
+README and changelog browsers:
 
-```json
-{
-  "checkIntervalMs": 3600000,
-  "autoUpdate": "notify"
-}
-```
+| Key | What it does |
+|---|---|
+| `j` / `k` or arrows | Moves in the list, or scrolls the detail view. |
+| `Enter` | Opens the selected item. |
+| `g` / `G` | Goes to the top or the bottom. |
+| `q` or `Esc` | Goes back to the list, or closes the list. |
 
-| Option | Values | Default |
-|--------|--------|---------|
-| `checkIntervalMs` | 1800000 (30min), 3600000 (1h), 21600000 (6h), 86400000 (1d) | 3600000 (1h) |
-| `autoUpdate` | disabled, notify, auto | notify |
+## Settings
 
-### Auto-update Modes
+Open `/unipi:settings` → Updater. The namespace is `updater`.
 
-- **disabled** — No update checks on session start
-- **notify** — Show overlay with changelog, user chooses Y/n
-- **auto** — Show countdown, auto-install after 5 seconds unless cancelled
+| Key | Default | What it does |
+|---|---|---|
+| `checkIntervalMs` | `3600000` (1 hour) | Minimum time between two npm checks. Options: 30 min, 1 hour, 6 hours, 1 day. |
+| `autoUpdate` | `notify` | `disabled`: no check. `notify`: the overlay asks you. `auto`: the overlay counts down 5 seconds, then installs. Press `n` to cancel and skip this version. |
 
-### Cache
+## How it works
 
-Last-check cache at `~/.unipi/cache/updater/last-check.json`:
+1. At session start, Updater reads `~/.unipi/cache/updater/last-check.json`.
+2. If the last check is older than `checkIntervalMs`, Updater gets the `latest` dist-tag from npm. The request stops after 10 seconds.
+3. Updater compares the versions. It never offers a lower version.
+4. If the new version is not skipped, the overlay opens. Updater gets the changelog for the new version from GitHub. If that fails, it uses the local `CHANGELOG.md`.
+5. The install command stops after 60 seconds. If it fails, the overlay shows the error. Press any key to close it.
 
-```json
-{
-  "lastCheck": "2026-05-01T12:00:00.000Z",
-  "latestVersion": "0.1.16",
-  "skippedVersion": "0.1.16"
-}
-```
+A failed npm check is silent. Updater then uses the cached result.
 
-## License
+## See also
 
-MIT
+- [Commands reference](../../docs/reference/commands.md)
+- [Settings reference](../../docs/reference/settings.md)
+- [Info Screen](../info-screen/README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/updater",
-  "version": "3.0.0-alpha.4",
+  "version": "3.0.0-alpha.40",
   "description": "Auto-updater, changelog browser, and readme browser for Unipi — checks npm registry, renders CHANGELOG.md and README.md files in TUI overlays",
   "type": "module",
   "main": "index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.4"
+    "@pi-unipi/core": "3.0.0-alpha.40"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",

package/src/channel.ts

@@ -0,0 +1,100 @@
+/**
+ * @pi-unipi/updater — release channel resolution (UNI-262)
+ *
+ * UniPi 3 ships on the npm `alpha` dist-tag while `latest` still points at the
+ * 2.x line. Comparing an alpha install against `latest` offered a downgrade.
+ * The channel to follow comes from, in order:
+ *   1. the pi settings package spec (`npm:@pi-unipi/unipi@alpha`) when its
+ *      version part is a dist-tag (not a pinned semver),
+ *   2. the installed version's prerelease id (`3.0.0-alpha.36` → `alpha`),
+ *   3. `latest`.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { compareVersions } from "@pi-unipi/core";
+
+export const UNIPI_PACKAGE = "@pi-unipi/unipi";
+
+/** `3.0.0-alpha.36` → `alpha`; stable → null. */
+export function prereleaseChannel(version: string): string | null {
+  const m = /^v?\d+\.\d+\.\d+-([0-9A-Za-z-]+)/.exec(version.trim());
+  if (!m) return null;
+  const id = m[1]!;
+  return /^\d+$/.test(id) ? null : id;
+}
+
+/** `npm:@pi-unipi/unipi@alpha` → `alpha`; pinned semver / no tag / other package → null. */
+export function channelFromSpec(spec: string): string | null {
+  const s = spec.trim().replace(/^npm:/, "");
+  if (!s.startsWith(`${UNIPI_PACKAGE}@`)) return null;
+  const tag = s.slice(UNIPI_PACKAGE.length + 1).trim();
+  if (!tag) return null;
+  // A pinned or ranged version is not a channel.
+  if (/^[\^~<>=v]?\d/.test(tag) || tag === "*") return null;
+  return tag;
+}
+
+/** pi's agent dir (honours PI_CODING_AGENT_DIR like pi itself). */
+export function piAgentDir(env: NodeJS.ProcessEnv = process.env): string {
+  const dir = env.PI_CODING_AGENT_DIR;
+  if (dir) return dir.startsWith("~") ? join(homedir(), dir.slice(1)) : dir;
+  return join(homedir(), ".pi", "agent");
+}
+
+/** The UniPi package spec from pi settings (project first, then global), if any. */
+export function readUnipiPackageSpec(cwd = process.cwd(), env: NodeJS.ProcessEnv = process.env): string | null {
+  const files = [join(cwd, ".pi", "settings.json"), join(piAgentDir(env), "settings.json")];
+  for (const file of files) {
+    try {
+      if (!existsSync(file)) continue;
+      const settings = JSON.parse(readFileSync(file, "utf8")) as { packages?: Array<string | { source?: string }> };
+      for (const pkg of settings.packages ?? []) {
+        const source = typeof pkg === "string" ? pkg : pkg?.source;
+        if (typeof source !== "string") continue;
+        const bare = source.trim().replace(/^npm:/, "");
+        if (bare === UNIPI_PACKAGE || bare.startsWith(`${UNIPI_PACKAGE}@`)) return source.trim();
+      }
+    } catch {
+      // Unreadable settings — try the next file.
+    }
+  }
+  return null;
+}
+
+/** The dist-tag this install follows. */
+export function resolveChannel(installedVersion: string, spec: string | null): string {
+  return (spec ? channelFromSpec(spec) : null) ?? prereleaseChannel(installedVersion) ?? "latest";
+}
+
+/**
+ * Pick the version to offer from a dist-tags map. A prerelease channel also
+ * considers `latest` so a graduation (3.0.0 stable) is still offered; a stable
+ * install never sees prerelease tags. Returns null if nothing usable.
+ */
+export function pickChannelVersion(distTags: Record<string, string> | undefined, channel: string): string | null {
+  if (!distTags) return null;
+  const candidates = [distTags[channel], channel !== "latest" ? distTags.latest : undefined]
+    .filter((v): v is string => typeof v === "string" && v.length > 0);
+  if (candidates.length === 0) return null;
+  return candidates.reduce((best, v) => (compareVersions(v, best) > 0 ? v : best));
+}
+
+/**
+ * UNI-272: which dist-tag the picked version came from. An alpha install
+ * offered 3.0.0 from `latest` (graduation) must install `latest` — installing
+ * `@alpha` again would reinstall the alpha it already has, and keep the
+ * install on the alpha channel forever. Ties go to the install's own channel.
+ */
+export function pickInstallTag(distTags: Record<string, string> | undefined, channel: string): string {
+  const picked = pickChannelVersion(distTags, channel);
+  if (!picked || !distTags) return channel;
+  if (distTags[channel] === picked) return channel;
+  return distTags.latest === picked ? "latest" : channel;
+}
+
+/** The `pi install` source for this channel. */
+export function installSpec(channel: string): string {
+  return channel === "latest" ? `npm:${UNIPI_PACKAGE}` : `npm:${UNIPI_PACKAGE}@${channel}`;
+}

package/src/checker.ts

@@ -1,90 +1,119 @@
 /**
  * @pi-unipi/updater — NPM registry checker
  *
- * Fetches latest version from npm registry, compares with installed version,
- * respects check interval from config/cache.
+ * Fetches the dist-tag of the install's release channel (UNI-262: an alpha
+ * install follows `alpha`, never `latest`), compares with the installed
+ * version, never offers a lower version, and respects the check interval.
  */
 
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { getInstalledPackageVersion } from "@pi-unipi/core";
 import { loadConfig } from "./settings.js";
 import { readLastCheck, writeLastCheck, isCheckDue } from "./cache.js";
 import { compareVersions, isNewerVersion } from "./version.js";
+import { pickChannelVersion, pickInstallTag, readUnipiPackageSpec, resolveChannel, UNIPI_PACKAGE } from "./channel.js";
 import type { UpdateCheckResult } from "../types.js";
 
-/** NPM registry URL for the unipi umbrella package */
-const NPM_REGISTRY_URL = "https://registry.npmjs.org/@pi-unipi/unipi";
+/** npm registry base; `UNIPI_UPDATER_REGISTRY` overrides it (tests / mirrors). */
+export function registryUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const base = (env.UNIPI_UPDATER_REGISTRY || "https://registry.npmjs.org").replace(/\/+$/, "");
+  return `${base}/-/package/${UNIPI_PACKAGE}/dist-tags`;
+}
 
 /** Resolve the installed version of @pi-unipi/unipi */
-function getInstalledVersion(): string {
-  // Walk up from this file to find the @pi-unipi/unipi package by name
-  const dir = new URL("..", import.meta.url).pathname;
-  return getInstalledPackageVersion(dir, "@pi-unipi/unipi");
+export function getInstalledVersion(): string {
+  // fileURLToPath, not URL.pathname: on Windows the latter is "/C:/…".
+  const dir = dirname(dirname(fileURLToPath(import.meta.url)));
+  return getInstalledPackageVersion(dir, UNIPI_PACKAGE);
 }
 
+/** The channel this install follows. */
+export function currentChannel(currentVersion = getInstalledVersion()): string {
+  return resolveChannel(currentVersion, readUnipiPackageSpec());
+}
 
 /** Build an update result without ever reporting downgrades as updates. */
-function toUpdateResult(latestVersion: string, currentVersion: string): UpdateCheckResult {
+function toUpdateResult(latestVersion: string, currentVersion: string, channel: string, installTag?: string): UpdateCheckResult {
   return {
     updateAvailable: isNewerVersion(latestVersion, currentVersion),
     latestVersion,
     currentVersion,
+    channel,
+    installTag: installTag ?? channel,
   };
 }
 
+export interface CheckOptions {
+  fetchImpl?: typeof fetch;
+  currentVersion?: string;
+  channel?: string;
+  /** Ignore the interval cache. */
+  force?: boolean;
+}
+
 /**
- * Check for updates from npm registry.
+ * Check for updates on this install's channel.
  * Respects check interval — skips if last check was recent.
- * Returns update status and version info.
  */
-export async function checkForUpdates(): Promise<UpdateCheckResult> {
-  const currentVersion = getInstalledVersion();
+export async function checkForUpdates(opts: CheckOptions = {}): Promise<UpdateCheckResult> {
+  const currentVersion = opts.currentVersion ?? getInstalledVersion();
+  const channel = opts.channel ?? currentChannel(currentVersion);
 
   try {
     const config = loadConfig();
 
-    // Check if we need to fetch (interval not elapsed). If the cached npm
-    // version is older than the installed version, ignore the interval and
-    // refresh: this happens immediately after a local/source release before
-    // the updater cache has seen the new npm dist-tag.
+    // A cache is only reused for the same channel (an old cache written by
+    // the pre-UNI-262 checker holds `latest`). If the cached version is older
+    // than the installed one, refresh: right after a release the cache has
+    // not seen the new dist-tag yet.
     const cache = readLastCheck();
-    if (cache && !isCheckDue(config.checkIntervalMs)) {
+    if (!opts.force && cache && (cache.channel ?? "latest") === channel && !isCheckDue(config.checkIntervalMs)) {
       if (compareVersions(cache.latestVersion, currentVersion) >= 0) {
-        return toUpdateResult(cache.latestVersion, currentVersion);
+        return toUpdateResult(cache.latestVersion, currentVersion, channel, cache.installTag);
       }
     }
 
-    // Fetch from npm registry
-    const response = await fetch(NPM_REGISTRY_URL, {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const response = await fetchImpl(registryUrl(), {
       headers: { Accept: "application/json" },
-      signal: AbortSignal.timeout(10000), // 10s timeout
+      signal: AbortSignal.timeout(10000),
     });
 
     if (!response.ok) {
       throw new Error(`HTTP ${response.status}: ${response.statusText}`);
     }
 
-    const data = await response.json() as { "dist-tags": { latest: string } };
-    const latestVersion = data["dist-tags"]?.latest;
+    const body = await response.json() as Record<string, unknown>;
+    // The dist-tags endpoint returns the map itself; the full packument nests it.
+    const tags = (body["dist-tags"] ?? body) as Record<string, string>;
+    const latestVersion = pickChannelVersion(tags, channel);
+    const installTag = pickInstallTag(tags, channel);
 
     if (!latestVersion) {
-      throw new Error("No dist-tags.latest in npm response");
+      throw new Error(`No dist-tag "${channel}" in npm response`);
     }
 
-    // Write cache
     writeLastCheck({
       lastCheck: new Date().toISOString(),
       latestVersion,
+      channel,
+      installTag,
+      skippedVersion: cache?.skippedVersion,
     });
 
-    return toUpdateResult(latestVersion, currentVersion);
+    return toUpdateResult(latestVersion, currentVersion, channel, installTag);
   } catch (err: unknown) {
-    // Network error — return cached info if available, but never suggest a
-    // downgrade from a stale cache.
+    // Network error — reuse cached info for this channel only, and never
+    // suggest a downgrade from a stale cache.
     const cache = readLastCheck();
+    const usable = cache && (cache.channel ?? "latest") === channel ? cache : null;
     return {
-      updateAvailable: cache ? isNewerVersion(cache.latestVersion, currentVersion) : false,
-      latestVersion: cache?.latestVersion ?? "",
+      updateAvailable: usable ? isNewerVersion(usable.latestVersion, currentVersion) : false,
+      latestVersion: usable?.latestVersion ?? "",
       currentVersion,
+      channel,
+      installTag: usable?.installTag ?? channel,
       error: err instanceof Error ? err.message : String(err) || "Unknown error",
     };
   }

package/src/index.ts

@@ -8,15 +8,15 @@
  * /unipi:readme and /unipi:changelog.
  */
 
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
+  bus,
   UNIPI_EVENTS,
   MODULES,
   UPDATER_COMMANDS,
   UNIPI_PREFIX,
-  emitEvent,
   getPackageVersion,
-  type UnipiUpdateCheckEvent,
 } from "@pi-unipi/core";
 import { registerCommands } from "./commands.js";
 import { loadConfig } from "./settings.js";
@@ -26,7 +26,7 @@ import { renderUpdateOverlay } from "./tui/update-overlay.js";
 import { loadUpdateChangelog } from "./remote-changelog.js";
 
 /** Package version */
-const VERSION = getPackageVersion(new URL("..", import.meta.url).pathname);
+const VERSION = getPackageVersion(fileURLToPath(new URL("..", import.meta.url)));
 
 export default function updaterExtension(pi: ExtensionAPI): void {
 
@@ -36,7 +36,7 @@ export default function updaterExtension(pi: ExtensionAPI): void {
   // Session lifecycle — check for updates and announce module
   pi.on("session_start", async (_event, ctx) => {
     // Emit MODULE_READY
-    emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
+    bus.emit(UNIPI_EVENTS.MODULE_READY, {
       name: MODULES.UPDATER,
       version: VERSION,
       commands: [
@@ -49,7 +49,7 @@ export default function updaterExtension(pi: ExtensionAPI): void {
     // Register info-screen group
     const infoRegistry = globalThis.__unipi_info_registry;
     if (infoRegistry) {
-      let cachedResult: { currentVersion: string; latestVersion: string; updateAvailable: boolean; lastCheck: string } | null = null;
+      let cachedResult: { currentVersion: string; latestVersion: string; updateAvailable: boolean; lastCheck: string; checkedAt: number } | null = null;
 
       infoRegistry.registerGroup({
         id: "updater",
@@ -66,56 +66,56 @@ export default function updaterExtension(pi: ExtensionAPI): void {
           ],
         },
         dataProvider: async () => {
+          const cfg = loadConfig();
           if (!cachedResult) {
             return {
-              current: VERSION,
-              latest: "checking...",
-              status: "⏳ Checking",
-              lastCheck: "never",
+              current: { value: VERSION },
+              latest: { value: "checking…" },
+              status: { value: "checking" },
+              lastCheck: { value: "never" },
+              raw: { value: "", raw: { current: VERSION, latest: null, available: false, checkedAt: 0, mode: cfg.autoUpdate } },
             };
           }
           return {
-            current: cachedResult.currentVersion,
-            latest: cachedResult.latestVersion,
-            status: cachedResult.updateAvailable ? "↑ Update available" : "✓ Up to date",
-            lastCheck: cachedResult.lastCheck || "never",
+            current: { value: cachedResult.currentVersion },
+            latest: { value: cachedResult.latestVersion },
+            status: { value: cachedResult.updateAvailable ? "update available" : "up to date" },
+            lastCheck: { value: cachedResult.lastCheck || "never" },
+            raw: {
+              value: "",
+              raw: {
+                current: cachedResult.currentVersion,
+                latest: cachedResult.latestVersion,
+                available: cachedResult.updateAvailable,
+                checkedAt: cachedResult.checkedAt,
+                mode: cfg.autoUpdate,
+              },
+            },
           };
         },
       });
 
       // Subscribe to events to update cached data
-      pi.events.on(UNIPI_EVENTS.UPDATE_CHECK, (data) => {
-        const payload = data as UnipiUpdateCheckEvent;
+      bus.on(pi, UNIPI_EVENTS.UPDATE_CHECK, (payload) => {
         cachedResult = {
           currentVersion: payload.currentVersion,
           latestVersion: payload.latestVersion,
           updateAvailable: payload.updateAvailable,
           lastCheck: new Date().toLocaleTimeString(),
+          checkedAt: Date.now(),
         };
-        emitEvent(pi, UNIPI_EVENTS.INFO_DATA_UPDATED, {
-          groupId: "updater",
-          keys: ["current", "latest", "status", "lastCheck"],
-        });
       });
 
-      pi.events.on(UNIPI_EVENTS.UPDATE_AVAILABLE, (_data: unknown) => {
+      bus.on(pi, UNIPI_EVENTS.UPDATE_AVAILABLE, () => {
         if (cachedResult) {
           cachedResult.updateAvailable = true;
         }
-        emitEvent(pi, UNIPI_EVENTS.INFO_DATA_UPDATED, {
-          groupId: "updater",
-          keys: ["status"],
-        });
       });
 
-      pi.events.on(UNIPI_EVENTS.UPDATE_APPLIED, (_data: unknown) => {
+      bus.on(pi, UNIPI_EVENTS.UPDATE_APPLIED, () => {
         if (cachedResult) {
           cachedResult.updateAvailable = false;
         }
-        emitEvent(pi, UNIPI_EVENTS.INFO_DATA_UPDATED, {
-          groupId: "updater",
-          keys: ["status"],
-        });
       });
     }
 
@@ -127,7 +127,7 @@ export default function updaterExtension(pi: ExtensionAPI): void {
       const result = await checkForUpdates();
 
       // Emit check event
-      emitEvent(pi, UNIPI_EVENTS.UPDATE_CHECK, result);
+      bus.emit(UNIPI_EVENTS.UPDATE_CHECK, result);
 
       if (!result.updateAvailable || result.error) return;
 
@@ -135,7 +135,7 @@ export default function updaterExtension(pi: ExtensionAPI): void {
       if (isVersionSkipped(result.latestVersion)) return;
 
       // Emit available event
-      emitEvent(pi, UNIPI_EVENTS.UPDATE_AVAILABLE, {
+      bus.emit(UNIPI_EVENTS.UPDATE_AVAILABLE, {
         currentVersion: result.currentVersion,
         latestVersion: result.latestVersion,
       });

package/src/installer.ts

@@ -6,7 +6,10 @@
 
 import { exec } from "child_process";
 import { promisify } from "util";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { getInstalledPackageVersion } from "@pi-unipi/core";
+import { installSpec } from "./channel.js";
 import type { InstallResult } from "../types.js";
 
 const execAsync = promisify(exec);
@@ -15,16 +18,18 @@ const execAsync = promisify(exec);
 const INSTALL_TIMEOUT_MS = 60000;
 
 /**
- * Install the latest version of @pi-unipi/unipi.
- * Uses pi CLI: `pi install npm:@pi-unipi/unipi`
+ * Install the newest @pi-unipi/unipi on `channel`.
+ * Uses pi CLI: `pi install npm:@pi-unipi/unipi[@<channel>]`
  * Returns structured result with success/failure info.
  */
-export async function installUpdate(): Promise<InstallResult> {
-  const thisDir = new URL("..", import.meta.url).pathname;
+export async function installUpdate(channel = "latest"): Promise<InstallResult> {
+  const thisDir = dirname(dirname(fileURLToPath(import.meta.url)));
 
   try {
+    // Install from the same channel the check used — a bare spec would pull
+    // `latest` and downgrade an alpha install (UNI-262).
     await execAsync(
-      "pi install npm:@pi-unipi/unipi",
+      `pi install ${installSpec(channel)}`,
       {
         timeout: INSTALL_TIMEOUT_MS,
         env: { ...process.env },

package/src/remote-changelog.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { UPDATER_DIRS } from "@pi-unipi/core";
+import { UPDATER_DIRS, compareVersions } from "@pi-unipi/core";
 import type { ChangelogEntry } from "../types.js";
 import { getNewerVersions, parseChangelogContent, parseChangelog, resolveChangelogPath } from "./changelog.js";
 
@@ -17,6 +17,16 @@ function cacheDirectory(opts?: RemoteChangelogOptions): string {
   return (opts?.cacheDir ?? UPDATER_DIRS.CACHE).replace("~", homedir());
 }
 
+/**
+ * Branches to try when the release tag is missing. Prereleases are pushed to
+ * a channel branch (`3.0.0-alpha.36` → `v3.0.0-alpha`); `main` holds the
+ * stable line only, so it would show the wrong changelog to an alpha install.
+ */
+export function fallbackRefs(version: string): string[] {
+  const m = /^v?(\d+\.\d+\.\d+-[0-9A-Za-z-]+)\.[0-9A-Za-z.-]+$/.exec(version);
+  return m ? [`v${m[1]}`, "main"] : ["main"];
+}
+
 export async function fetchRemoteChangelog(version: string, opts: RemoteChangelogOptions = {}): Promise<string | null> {
   const cacheDir = cacheDirectory(opts);
   const cachePath = join(cacheDir, `changelog-${version}.md`);
@@ -31,10 +41,11 @@ export async function fetchRemoteChangelog(version: string, opts: RemoteChangelo
   try {
     let response = await fetchImpl(`${CHANGELOG_RAW_BASE}/v${version}/CHANGELOG.md`, { signal });
     // The release tag is immutable, so its changelog is safe to cache forever.
-    // The `main` fallback (tag not pushed yet) is not: never cache it.
+    // The branch fallbacks (tag not pushed yet) are not: never cache them.
     const cacheable = response.ok;
-    if (response.status === 404) {
-      response = await fetchImpl(`${CHANGELOG_RAW_BASE}/main/CHANGELOG.md`, { signal });
+    for (const ref of fallbackRefs(version)) {
+      if (response.status !== 404) break;
+      response = await fetchImpl(`${CHANGELOG_RAW_BASE}/${ref}/CHANGELOG.md`, { signal });
     }
     if (!response.ok) return null;
     const content = await response.text();
@@ -55,7 +66,9 @@ export async function loadUpdateChangelog(
 ): Promise<ChangelogEntry[]> {
   const remote = await fetchRemoteChangelog(latestVersion, opts);
   const entries = remote === null ? [] : parseChangelogContent(remote);
-  const newer = remote === null ? [] : getNewerVersions(entries, currentVersion);
+  const upTo = (list: ChangelogEntry[]) =>
+    list.filter((e) => e.version === "Unreleased" || compareVersions(e.version, latestVersion) <= 0);
+  const newer = remote === null ? [] : upTo(getNewerVersions(entries, currentVersion));
   if (newer.length > 0) return newer;
-  return getNewerVersions(parseChangelog(resolveChangelogPath()), currentVersion);
+  return upTo(getNewerVersions(parseChangelog(resolveChangelogPath()), currentVersion));
 }

package/src/settings.ts

@@ -46,19 +46,25 @@ registerSettings({
           key: "checkIntervalMs",
           type: "enum",
           label: "Check interval",
+          plainOptions: true,
+          description: "How often to check npm for updates.",
           options: [
             { value: "1800000", label: "30 min" },
             { value: "3600000", label: "1 hour" },
             { value: "21600000", label: "6 hours" },
             { value: "86400000", label: "daily" },
           ],
-          description: "How often to check npm for updates",
         },
         {
           key: "autoUpdate",
           type: "enum",
           label: "Auto update",
-          options: ["disabled", "notify", "auto"],
+          description: "What happens when an update is found.",
+          options: [
+            { value: "disabled", label: "disabled", description: "check nothing; update manually" },
+            { value: "notify", label: "notify", description: "tell you; you install" },
+            { value: "auto", label: "auto", description: "install the update itself" },
+          ],
         },
       ],
     },

package/src/tui/changelog-overlay.ts

@@ -5,10 +5,11 @@
  */
 
 import { existsSync } from "fs";
+import { fileURLToPath } from "node:url";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { parseChangelog, resolveChangelogPath } from "../changelog.js";
 import { renderMarkdown } from "../markdown.js";
-import { getInstalledPackageVersion } from "@pi-unipi/core";
+import { getInstalledPackageVersion, compareVersions } from "@pi-unipi/core";
 import { createListDetailOverlay } from "./list-detail-overlay.js";
 import type { ChangelogEntry } from "../../types.js";
 
@@ -17,7 +18,7 @@ import type { ChangelogEntry } from "../../types.js";
  */
 export function renderChangelogOverlay() {
   const installedVersion = getInstalledPackageVersion(
-    new URL("..", import.meta.url).pathname,
+    fileURLToPath(new URL("..", import.meta.url)),
     "@pi-unipi/unipi",
   );
 
@@ -39,12 +40,7 @@ export function renderChangelogOverlay() {
       } else if (entry.version === installedVersion) {
         label = theme.fg("success", "✓ Current");
       } else {
-        const pa = entry.version.split(".").map(Number);
-        const pb = installedVersion.split(".").map(Number);
-        const isNewer =
-          pa[0]! > pb[0]! ||
-          (pa[0] === pb[0] && pa[1]! > pb[1]!) ||
-          (pa[0] === pb[0] && pa[1] === pb[1] && pa[2]! > pb[2]!);
+        const isNewer = compareVersions(entry.version, installedVersion) > 0;
         label = isNewer ? theme.fg("warning", "↑ New") : "";
       }
 

package/src/tui/update-overlay.ts

@@ -93,7 +93,8 @@ export function renderUpdateOverlay(checkResult: UpdateCheckResult, providedNewe
       state.installing = true;
       tui.requestRender();
 
-      const result = await installUpdate();
+      // UNI-272: the tag the offered version came from (alpha → 3.0.0 stable installs `latest`).
+      const result = await installUpdate(state.result.installTag ?? state.result.channel ?? "latest");
       if (result.success) {
         done({ updated: true });
       } else {

package/types.ts

@@ -20,6 +20,10 @@ export interface LastCheckCache {
   latestVersion: string;
   /** Version the user chose to skip */
   skippedVersion?: string;
+  /** npm dist-tag the check followed (absent in pre-UNI-262 caches = "latest") */
+  channel?: string;
+  /** UNI-272: dist-tag to install the offered version from (≠ channel on graduation). */
+  installTag?: string;
 }
 
 /** A parsed changelog version entry */
@@ -54,6 +58,11 @@ export interface UpdateCheckResult {
   latestVersion: string;
   /** Currently installed version */
   currentVersion: string;
+  /** npm dist-tag this install follows ("alpha", "latest", …) */
+  channel?: string;
+  /** UNI-272: the dist-tag the offered version comes from — install from this
+   * (an alpha install offered 3.0.0 stable installs `latest`, leaving alpha). */
+  installTag?: string;
   /** Error message if check failed */
   error?: string;
 }