@mnemom/mnemom 0.17.2-next.7 → 0.17.2-next.8

package/dist/lib/cli-config.d.ts

@@ -17,6 +17,7 @@
  * Membership can change after it's stored — consumers must treat a server
  * 403 as the truth (the claim path already renders the teaching list).
  */
+import type { UpdatePrefs } from "./update/decide.js";
 export interface ActiveOrg {
     org_id: string;
     slug: string;
@@ -24,6 +25,8 @@ export interface ActiveOrg {
 }
 export interface CliConfig {
     activeOrg?: ActiveOrg;
+    /** Auto-update preferences (`mnemom config set update.channel|update.mode`). */
+    update?: UpdatePrefs;
 }
 /** Load the config; a missing or corrupt file degrades to `{}`. */
 export declare function loadCliConfig(): CliConfig;
@@ -31,3 +34,8 @@ export declare function loadCliConfig(): CliConfig;
 export declare function setActiveOrg(org: ActiveOrg | null): void;
 /** The active org, or undefined when none is set. */
 export declare function getActiveOrg(): ActiveOrg | undefined;
+/**
+ * Set (or with `undefined`, clear) one auto-update preference. Validation is
+ * the caller's job (commands/config.ts) — this only persists.
+ */
+export declare function setUpdatePref<K extends keyof UpdatePrefs>(key: K, value: UpdatePrefs[K] | undefined): void;

package/dist/lib/cli-config.js

@@ -68,3 +68,16 @@ export function setActiveOrg(org) {
 export function getActiveOrg() {
     return loadCliConfig().activeOrg;
 }
+/**
+ * Set (or with `undefined`, clear) one auto-update preference. Validation is
+ * the caller's job (commands/config.ts) — this only persists.
+ */
+export function setUpdatePref(key, value) {
+    const config = loadCliConfig();
+    const update = Object.fromEntries(Object.entries({ ...config.update, [key]: value }).filter(([, v]) => v !== undefined));
+    if (Object.keys(update).length === 0)
+        delete config.update;
+    else
+        config.update = update;
+    saveCliConfig(config);
+}

package/dist/lib/update/action.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The commander-action wrapper for `mnemom update` / `mnemom config`: print
+ * the error and exit 1. Injected so the error path is testable.
+ */
+export interface ActionIO {
+    error(...args: unknown[]): void;
+    exit(code: number): void;
+}
+export declare function runAction(fn: () => void | Promise<void>, io?: ActionIO): Promise<void>;

package/dist/lib/update/action.js

@@ -0,0 +1,17 @@
+/**
+ * The commander-action wrapper for `mnemom update` / `mnemom config`: print
+ * the error and exit 1. Injected so the error path is testable.
+ */
+const realIO = {
+    error: (...args) => console.error(...args),
+    exit: (code) => process.exit(code),
+};
+export async function runAction(fn, io = realIO) {
+    try {
+        await fn();
+    }
+    catch (error) {
+        io.error("Error:", error instanceof Error ? error.message : error);
+        io.exit(1);
+    }
+}

package/dist/lib/update/decide.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Auto-update policy — the pure core.
+ *
+ * Every decision the updater makes lives here as a side-effect-free function of
+ * its inputs (current version, registry dist-tags, config, env, install method,
+ * persisted state, clock) so each branch is directly testable. The drivers
+ * (`startup.ts`, `worker.ts`, `commands/update.ts`) only gather inputs and act.
+ *
+ * Channels:
+ *   latest — the stable dist-tag. A prerelease is NEVER auto-installed here,
+ *            even if it is (mis)tagged `latest` (the 2026-09-22 next.9 incident:
+ *            OIDC publishing can't move a dist-tag back, so the guard is ours).
+ *   next   — max(next, latest) by SemVer, so a next user rides onto each stable
+ *            cut instead of being stranded on an older prerelease. Honoured only
+ *            for entitled callers (internal cohort, staff, `cli_next` invite —
+ *            GET /v1/cli/channel-entitlement); otherwise it behaves as latest.
+ *
+ * Never downgrades automatically: switching next → latest while ahead of latest
+ * keeps the current build until latest overtakes it (`mnemom update --force`).
+ */
+export type UpdateChannel = "latest" | "next";
+export type UpdateMode = "auto" | "notify" | "off";
+export declare const UPDATE_CHANNELS: readonly UpdateChannel[];
+export declare const UPDATE_MODES: readonly UpdateMode[];
+export declare const PACKAGE_NAME = "@mnemom/mnemom";
+/** How often the background worker polls the registry, per channel. */
+export declare const CHECK_INTERVAL_MS: Record<UpdateChannel, number>;
+/** Cached channel entitlement is trusted for this long before re-asking. */
+export declare const ENTITLEMENT_TTL_MS: number;
+/** At most one "update available" line per this window. */
+export declare const NOTIFY_INTERVAL_MS: number;
+/** Failure backoff: 1d, 2d, 4d … capped at 7d. */
+export declare const BACKOFF_BASE_MS: number;
+export declare const BACKOFF_MAX_MS: number;
+/** How the running CLI was installed — decides whether it can replace itself. */
+export type InstallMethod = "npm-global" | "pnpm-global" | "yarn-global" | "bun-global" | "npx" | "project" | "dev" | "unknown";
+export interface DistTags {
+    latest?: string;
+    next?: string;
+}
+export interface EntitlementCache {
+    next: boolean;
+    checkedAt: number;
+}
+/** ~/.mnemom/update-state.json */
+export interface UpdateState {
+    lastCheck?: number;
+    /** Newest installable version the last check found (for notify mode). */
+    available?: string;
+    /** Written after a successful background install; shown once, then cleared. */
+    pending?: {
+        from: string;
+        to: string;
+        channel: UpdateChannel;
+    };
+    lastNotified?: number;
+    failures?: number;
+    backoffUntil?: number;
+    lastError?: string;
+    /** Global prefix isn't writable (EACCES) — stop trying, tell the user how to fix. */
+    installBlocked?: boolean;
+    entitlement?: EntitlementCache;
+    /** Install method the worker last detected (startup can't afford `npm root -g`). */
+    method?: InstallMethod;
+}
+export interface UpdatePrefs {
+    channel?: UpdateChannel;
+    mode?: UpdateMode;
+}
+export interface ResolvedSettings {
+    channel: UpdateChannel;
+    mode: UpdateMode;
+    /** Why mode was forced to off, when it was. */
+    offReason?: string;
+}
+export declare function isUpdateChannel(v: unknown): v is UpdateChannel;
+export declare function isUpdateMode(v: unknown): v is UpdateMode;
+/** Channel precedence: flag > MNEMOM_UPDATE_CHANNEL > config.json > latest. */
+export declare function resolveChannel(prefs: UpdatePrefs, env: Record<string, string | undefined>, flag?: UpdateChannel): UpdateChannel;
+/** Mode precedence: flag > MNEMOM_UPDATE_MODE > config.json > auto. */
+export declare function resolveMode(prefs: UpdatePrefs, env: Record<string, string | undefined>, flag?: UpdateMode): UpdateMode;
+/**
+ * Settings precedence: flag > env > config.json > built-in (latest / auto).
+ * Then hard overrides that force `off` regardless: the kill switch, CI, and a
+ * non-interactive stdout (CI images and pipelines must never mutate themselves).
+ * An invalid env value is ignored rather than fatal — a typo must not break
+ * every command.
+ */
+export declare function resolveSettings(input: {
+    prefs: UpdatePrefs;
+    env: Record<string, string | undefined>;
+    isTTY: boolean;
+    flags?: UpdatePrefs;
+}): ResolvedSettings;
+/** The channel actually honoured: `next` requires a positive entitlement. */
+export declare function effectiveChannel(requested: UpdateChannel, entitledToNext: boolean): UpdateChannel;
+/** Whether the cached entitlement answer is still fresh enough to use. */
+export declare function entitlementFresh(cache: EntitlementCache | undefined, now: number): boolean;
+/**
+ * The version a channel points at, or undefined when the registry offered
+ * nothing usable. Invalid tag values are dropped (defence against a malformed
+ * registry response).
+ */
+export declare function pickTarget(tags: DistTags, channel: UpdateChannel): string | undefined;
+/** Whether the background worker should poll the registry now. */
+export declare function shouldCheck(state: UpdateState, channel: UpdateChannel, now: number): boolean;
+export declare function backoffDelay(failures: number): number;
+export declare function canSelfUpdate(method: InstallMethod): boolean;
+export type UpdateAction = {
+    kind: "noop";
+    reason: string;
+} | {
+    kind: "notify";
+    version: string;
+    reason: string;
+} | {
+    kind: "install";
+    version: string;
+};
+/**
+ * The single decision: given where the registry is and how we're installed,
+ * install / notify / do nothing. `force` (explicit `mnemom update --force`)
+ * permits a downgrade to the channel's target.
+ */
+export declare function decide(input: {
+    current: string;
+    target: string | undefined;
+    mode: UpdateMode;
+    method: InstallMethod;
+    installBlocked?: boolean;
+    force?: boolean;
+}): UpdateAction;
+/** The command a human should run to upgrade, for the given install method. */
+export declare function manualUpgradeCommand(method: InstallMethod, version: string): string;
+export interface StartupNotice {
+    message: string;
+    /** State to persist after showing the notice. */
+    patch: Partial<UpdateState>;
+}
+/**
+ * What (if anything) to print on stderr at startup. A completed background
+ * install is announced once — only when the running binary IS the new version,
+ * so a user still inside an old process doesn't see a false "updated". Otherwise
+ * an available-but-not-installed version is surfaced at most once a day.
+ */
+export declare function startupNotice(input: {
+    current: string;
+    state: UpdateState;
+    mode: UpdateMode;
+    method: InstallMethod;
+    now: number;
+}): StartupNotice | null;

package/dist/lib/update/decide.js

@@ -0,0 +1,195 @@
+/**
+ * Auto-update policy — the pure core.
+ *
+ * Every decision the updater makes lives here as a side-effect-free function of
+ * its inputs (current version, registry dist-tags, config, env, install method,
+ * persisted state, clock) so each branch is directly testable. The drivers
+ * (`startup.ts`, `worker.ts`, `commands/update.ts`) only gather inputs and act.
+ *
+ * Channels:
+ *   latest — the stable dist-tag. A prerelease is NEVER auto-installed here,
+ *            even if it is (mis)tagged `latest` (the 2026-09-22 next.9 incident:
+ *            OIDC publishing can't move a dist-tag back, so the guard is ours).
+ *   next   — max(next, latest) by SemVer, so a next user rides onto each stable
+ *            cut instead of being stranded on an older prerelease. Honoured only
+ *            for entitled callers (internal cohort, staff, `cli_next` invite —
+ *            GET /v1/cli/channel-entitlement); otherwise it behaves as latest.
+ *
+ * Never downgrades automatically: switching next → latest while ahead of latest
+ * keeps the current build until latest overtakes it (`mnemom update --force`).
+ */
+import { compareVersions, isPrerelease, isValidVersion } from "./semver.js";
+export const UPDATE_CHANNELS = ["latest", "next"];
+export const UPDATE_MODES = ["auto", "notify", "off"];
+export const PACKAGE_NAME = "@mnemom/mnemom";
+const HOUR = 60 * 60 * 1000;
+const DAY = 24 * HOUR;
+/** How often the background worker polls the registry, per channel. */
+export const CHECK_INTERVAL_MS = {
+    latest: DAY,
+    next: 6 * HOUR,
+};
+/** Cached channel entitlement is trusted for this long before re-asking. */
+export const ENTITLEMENT_TTL_MS = DAY;
+/** At most one "update available" line per this window. */
+export const NOTIFY_INTERVAL_MS = DAY;
+/** Failure backoff: 1d, 2d, 4d … capped at 7d. */
+export const BACKOFF_BASE_MS = DAY;
+export const BACKOFF_MAX_MS = 7 * DAY;
+export function isUpdateChannel(v) {
+    return typeof v === "string" && UPDATE_CHANNELS.includes(v);
+}
+export function isUpdateMode(v) {
+    return typeof v === "string" && UPDATE_MODES.includes(v);
+}
+function truthyEnv(v) {
+    return v !== undefined && v !== "" && v !== "0" && v.toLowerCase() !== "false";
+}
+/** Channel precedence: flag > MNEMOM_UPDATE_CHANNEL > config.json > latest. */
+export function resolveChannel(prefs, env, flag) {
+    const fromEnv = env.MNEMOM_UPDATE_CHANNEL;
+    return flag ?? (isUpdateChannel(fromEnv) ? fromEnv : undefined) ?? prefs.channel ?? "latest";
+}
+/** Mode precedence: flag > MNEMOM_UPDATE_MODE > config.json > auto. */
+export function resolveMode(prefs, env, flag) {
+    const fromEnv = env.MNEMOM_UPDATE_MODE;
+    return flag ?? (isUpdateMode(fromEnv) ? fromEnv : undefined) ?? prefs.mode ?? "auto";
+}
+/**
+ * Settings precedence: flag > env > config.json > built-in (latest / auto).
+ * Then hard overrides that force `off` regardless: the kill switch, CI, and a
+ * non-interactive stdout (CI images and pipelines must never mutate themselves).
+ * An invalid env value is ignored rather than fatal — a typo must not break
+ * every command.
+ */
+export function resolveSettings(input) {
+    const { prefs, env, isTTY, flags } = input;
+    const channel = resolveChannel(prefs, env, flags?.channel);
+    const mode = resolveMode(prefs, env, flags?.mode);
+    if (truthyEnv(env.MNEMOM_DISABLE_AUTOUPDATE)) {
+        return { channel, mode: "off", offReason: "MNEMOM_DISABLE_AUTOUPDATE is set" };
+    }
+    if (truthyEnv(env.CI))
+        return { channel, mode: "off", offReason: "running in CI" };
+    if (!isTTY)
+        return { channel, mode: "off", offReason: "not an interactive terminal" };
+    return { channel, mode };
+}
+/** The channel actually honoured: `next` requires a positive entitlement. */
+export function effectiveChannel(requested, entitledToNext) {
+    return requested === "next" && entitledToNext ? "next" : "latest";
+}
+/** Whether the cached entitlement answer is still fresh enough to use. */
+export function entitlementFresh(cache, now) {
+    return cache !== undefined && now - cache.checkedAt < ENTITLEMENT_TTL_MS;
+}
+/**
+ * The version a channel points at, or undefined when the registry offered
+ * nothing usable. Invalid tag values are dropped (defence against a malformed
+ * registry response).
+ */
+export function pickTarget(tags, channel) {
+    const latest = tags.latest && isValidVersion(tags.latest) ? tags.latest : undefined;
+    // Mis-tag guard: the stable channel never offers a prerelease.
+    const stable = latest && !isPrerelease(latest) ? latest : undefined;
+    if (channel === "latest")
+        return stable;
+    const next = tags.next && isValidVersion(tags.next) ? tags.next : undefined;
+    if (!next)
+        return stable;
+    if (!stable)
+        return next;
+    return compareVersions(next, stable) >= 0 ? next : stable;
+}
+/** Whether the background worker should poll the registry now. */
+export function shouldCheck(state, channel, now) {
+    if (state.backoffUntil !== undefined && now < state.backoffUntil)
+        return false;
+    if (state.lastCheck === undefined)
+        return true;
+    return now - state.lastCheck >= CHECK_INTERVAL_MS[channel];
+}
+export function backoffDelay(failures) {
+    const exp = BACKOFF_BASE_MS * 2 ** Math.max(0, failures - 1);
+    return Math.min(exp, BACKOFF_MAX_MS);
+}
+export function canSelfUpdate(method) {
+    return method === "npm-global";
+}
+/**
+ * The single decision: given where the registry is and how we're installed,
+ * install / notify / do nothing. `force` (explicit `mnemom update --force`)
+ * permits a downgrade to the channel's target.
+ */
+export function decide(input) {
+    const { current, target, mode, method, installBlocked, force } = input;
+    if (mode === "off")
+        return { kind: "noop", reason: "updates are off" };
+    if (!target)
+        return { kind: "noop", reason: "no version published on this channel" };
+    const cmp = compareVersions(target, current);
+    if (cmp === 0)
+        return { kind: "noop", reason: "already on the newest version" };
+    if (cmp < 0 && !force)
+        return { kind: "noop", reason: "current build is newer than the channel" };
+    if (!canSelfUpdate(method)) {
+        return { kind: "notify", version: target, reason: `installed via ${method}` };
+    }
+    if (installBlocked) {
+        return { kind: "notify", version: target, reason: "global npm prefix is not writable" };
+    }
+    if (mode === "notify")
+        return { kind: "notify", version: target, reason: "update.mode is notify" };
+    return { kind: "install", version: target };
+}
+/** The command a human should run to upgrade, for the given install method. */
+export function manualUpgradeCommand(method, version) {
+    const spec = `${PACKAGE_NAME}@${version}`;
+    switch (method) {
+        case "pnpm-global":
+            return `pnpm add -g ${spec}`;
+        case "yarn-global":
+            return `yarn global add ${spec}`;
+        case "bun-global":
+            return `bun add -g ${spec}`;
+        case "project":
+            return `npm install ${spec}  (in your project)`;
+        case "npx":
+            return `npx ${spec}`;
+        default:
+            return `npm install -g ${spec}`;
+    }
+}
+/**
+ * What (if anything) to print on stderr at startup. A completed background
+ * install is announced once — only when the running binary IS the new version,
+ * so a user still inside an old process doesn't see a false "updated". Otherwise
+ * an available-but-not-installed version is surfaced at most once a day.
+ */
+export function startupNotice(input) {
+    const { current, state, mode, method, now } = input;
+    if (state.pending && state.pending.to === current) {
+        return {
+            message: `✓ mnemom updated ${state.pending.from} → ${current} (${state.pending.channel})`,
+            patch: { pending: undefined },
+        };
+    }
+    if (mode === "off" || !state.available || !isValidVersion(state.available))
+        return null;
+    if (compareVersions(state.available, current) <= 0)
+        return null;
+    // In auto mode with a working self-update, the worker installs it — stay quiet.
+    if (mode === "auto" && canSelfUpdate(method) && !state.installBlocked)
+        return null;
+    if (state.lastNotified !== undefined && now - state.lastNotified < NOTIFY_INTERVAL_MS)
+        return null;
+    const cmd = !canSelfUpdate(method)
+        ? ` — run: ${manualUpgradeCommand(method, state.available)}`
+        : state.installBlocked
+            ? ` — the global npm prefix isn't writable; run: ${manualUpgradeCommand(method, state.available)} (see https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)`
+            : " — run: mnemom update";
+    return {
+        message: `mnemom ${state.available} is available (you have ${current})${cmd}`,
+        patch: { lastNotified: now },
+    };
+}

package/dist/lib/update/doctor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The "auto-update" row for `mnemom agent doctor`: can this install update
+ * itself, on which channel, and did the last check go wrong? `updateDoctorRow`
+ * is pure; `probeUpdateStatus` gathers the real inputs.
+ */
+import { type InstallMethod, type ResolvedSettings, type UpdateState } from "./decide.js";
+export interface DoctorRow {
+    mark: "ok" | "warn" | "info";
+    text: string;
+    hint?: string;
+}
+export declare function updateDoctorRow(input: {
+    current: string;
+    settings: ResolvedSettings;
+    method: InstallMethod;
+    state: UpdateState;
+}): DoctorRow;
+export declare function probeUpdateStatus(): Promise<DoctorRow>;

package/dist/lib/update/doctor.js

@@ -0,0 +1,63 @@
+/**
+ * The "auto-update" row for `mnemom agent doctor`: can this install update
+ * itself, on which channel, and did the last check go wrong? `updateDoctorRow`
+ * is pure; `probeUpdateStatus` gathers the real inputs.
+ */
+import { CLI_VERSION } from "../../version.js";
+import { canSelfUpdate, manualUpgradeCommand, resolveSettings, } from "./decide.js";
+import { classifyInstall } from "./install-method.js";
+import { loadUpdateState } from "./state.js";
+import { entryRealpath, loadUpdatePrefs, npmGlobalRoot } from "./system.js";
+export function updateDoctorRow(input) {
+    const { current, settings, method, state } = input;
+    const version = state.available ?? "latest";
+    if (settings.mode === "off") {
+        return {
+            mark: "info",
+            text: `auto-update: off${settings.offReason ? ` (${settings.offReason})` : ""}`,
+            hint: "check manually with `mnemom update --check`",
+        };
+    }
+    if (!canSelfUpdate(method)) {
+        return {
+            mark: "info",
+            text: `auto-update: can't self-update (installed via ${method})`,
+            hint: `upgrade with: ${manualUpgradeCommand(method, version)}`,
+        };
+    }
+    if (state.installBlocked) {
+        return {
+            mark: "warn",
+            text: "auto-update: the global npm prefix is not writable",
+            hint: "fix npm's global prefix permissions (https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally), then run `mnemom update`",
+        };
+    }
+    if (settings.channel === "next" && state.entitlement?.next === false) {
+        return {
+            mark: "warn",
+            text: "auto-update: update.channel=next, but this account isn't invited to it — following latest",
+            hint: "ask your Mnemom contact for a next-channel invite, or `mnemom config set update.channel latest`",
+        };
+    }
+    if (state.lastError) {
+        return {
+            mark: "warn",
+            text: `auto-update: last check failed (${state.lastError})`,
+            hint: "it retries automatically with backoff; `mnemom update` retries now",
+        };
+    }
+    const pending = state.available ? `, ${state.available} available` : "";
+    return {
+        mark: "ok",
+        text: `auto-update: ${settings.mode} on ${settings.channel} (v${current}${pending})`,
+    };
+}
+export async function probeUpdateStatus() {
+    const settings = resolveSettings({
+        prefs: loadUpdatePrefs(),
+        env: process.env,
+        isTTY: process.stdout.isTTY === true,
+    });
+    const method = classifyInstall(entryRealpath(process.argv[1]), await npmGlobalRoot());
+    return updateDoctorRow({ current: CLI_VERSION, settings, method, state: loadUpdateState() });
+}

package/dist/lib/update/install-method.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Classify how the running CLI was installed, from the realpath of its entry
+ * script. Only a plain `npm install -g` is self-updatable; every other shape
+ * gets the right manual command instead of an `npm i -g` that would install a
+ * second, shadowed copy.
+ */
+import type { InstallMethod } from "./decide.js";
+/**
+ * @param entryRealpath realpath of process.argv[1] (the bin symlink resolved)
+ * @param npmGlobalRoot output of `npm root -g`, or undefined if npm is unavailable
+ */
+export declare function classifyInstall(entryRealpath: string, npmGlobalRoot: string | undefined): InstallMethod;

package/dist/lib/update/install-method.js

@@ -0,0 +1,33 @@
+/**
+ * Classify how the running CLI was installed, from the realpath of its entry
+ * script. Only a plain `npm install -g` is self-updatable; every other shape
+ * gets the right manual command instead of an `npm i -g` that would install a
+ * second, shadowed copy.
+ */
+/** Normalise Windows separators so one set of patterns covers every platform. */
+function norm(p) {
+    return p.replace(/\\/g, "/");
+}
+/**
+ * @param entryRealpath realpath of process.argv[1] (the bin symlink resolved)
+ * @param npmGlobalRoot output of `npm root -g`, or undefined if npm is unavailable
+ */
+export function classifyInstall(entryRealpath, npmGlobalRoot) {
+    const p = norm(entryRealpath);
+    if (/\.(c|m)?ts$/.test(p))
+        return "dev";
+    if (p.includes("/_npx/"))
+        return "npx";
+    if (p.includes("/.pnpm/") || p.includes("/pnpm/global/"))
+        return "pnpm-global";
+    if (p.includes("/.yarn/") || p.includes("/yarn/global/"))
+        return "yarn-global";
+    if (p.includes("/.bun/"))
+        return "bun-global";
+    if (npmGlobalRoot && p.startsWith(`${norm(npmGlobalRoot).replace(/\/$/, "")}/@mnemom/mnemom/`)) {
+        return "npm-global";
+    }
+    if (p.includes("/node_modules/@mnemom/mnemom/"))
+        return "project";
+    return "unknown";
+}

package/dist/lib/update/min-version.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Turn the server's minimum-CLI hard-fail (lib/version-gate.ts) into a
+ * one-retry fix: when update.mode is auto and this install can update itself,
+ * install the newest stable release satisfying the floor, in the foreground,
+ * and ask the user to re-run. Synchronous because the gate is.
+ */
+import { spawnSync, type StdioOptions } from "node:child_process";
+import { type InstallMethod, type ResolvedSettings } from "./decide.js";
+import { type NpmInvocation } from "./system.js";
+export interface FloorUpgradeDeps {
+    settings(): ResolvedSettings;
+    method(): InstallMethod;
+    /** The same install lock the worker and `mnemom update` hold. */
+    acquireLock(): (() => void) | null;
+    /** Install `spec` (an npm version range); true on success. */
+    install(spec: string): boolean;
+    write(chunk: string): void;
+}
+/**
+ * Returns true when the CLI was upgraded. Only in `auto` mode — `notify` means
+ * "never install without my say-so", even for a server floor. The floor is
+ * untrusted header input: it must be a plain release version before it goes
+ * anywhere near argv. Another installer holding the lock → don't race it.
+ */
+export declare function upgradeToFloor(floor: string, deps: FloorUpgradeDeps): boolean;
+/** Sync npm spawn (the gate is synchronous); never a shell. */
+export declare function spawnNpmSync(inv: NpmInvocation | null, args: string[], opts: {
+    stdio?: StdioOptions;
+    timeout: number;
+}, spawn?: typeof spawnSync): {
+    ok: boolean;
+    stdout: string;
+};
+export declare function defaultFloorUpgradeDeps(): FloorUpgradeDeps;

package/dist/lib/update/min-version.js

@@ -0,0 +1,69 @@
+/**
+ * Turn the server's minimum-CLI hard-fail (lib/version-gate.ts) into a
+ * one-retry fix: when update.mode is auto and this install can update itself,
+ * install the newest stable release satisfying the floor, in the foreground,
+ * and ask the user to re-run. Synchronous because the gate is.
+ */
+import { spawnSync } from "node:child_process";
+import { canSelfUpdate, PACKAGE_NAME, resolveSettings, } from "./decide.js";
+import { classifyInstall } from "./install-method.js";
+import { isValidVersion, isPrerelease } from "./semver.js";
+import { acquireLock } from "./state.js";
+import { entryRealpath, loadUpdatePrefs, npmInvocation } from "./system.js";
+/**
+ * Returns true when the CLI was upgraded. Only in `auto` mode — `notify` means
+ * "never install without my say-so", even for a server floor. The floor is
+ * untrusted header input: it must be a plain release version before it goes
+ * anywhere near argv. Another installer holding the lock → don't race it.
+ */
+export function upgradeToFloor(floor, deps) {
+    if (!isValidVersion(floor) || isPrerelease(floor))
+        return false;
+    if (deps.settings().mode !== "auto")
+        return false;
+    if (!canSelfUpdate(deps.method()))
+        return false;
+    const release = deps.acquireLock();
+    if (!release)
+        return false;
+    try {
+        deps.write(`\nUpdating the Mnemom CLI to meet the server minimum (v${floor})…\n`);
+        // A range, not a tag: npm picks the newest STABLE version ≥ floor (ranges
+        // exclude prereleases), so a mis-tagged `latest` can't sneak in here.
+        return deps.install(`${PACKAGE_NAME}@>=${floor}`);
+    }
+    finally {
+        release();
+    }
+}
+/** Sync npm spawn (the gate is synchronous); never a shell. */
+export function spawnNpmSync(inv, args, opts, spawn = spawnSync) {
+    if (!inv)
+        return { ok: false, stdout: "" };
+    const r = spawn(inv.file, [...inv.prefix, ...args], {
+        encoding: "utf8",
+        windowsHide: true,
+        ...opts,
+    });
+    return { ok: r.status === 0, stdout: typeof r.stdout === "string" ? r.stdout : "" };
+}
+export function defaultFloorUpgradeDeps() {
+    const inv = npmInvocation();
+    return {
+        settings: () => resolveSettings({
+            prefs: loadUpdatePrefs(),
+            env: process.env,
+            isTTY: process.stdout.isTTY === true,
+        }),
+        method: () => {
+            const root = spawnNpmSync(inv, ["root", "-g"], { timeout: 15_000 });
+            return classifyInstall(entryRealpath(process.argv[1]), root.ok ? root.stdout.trim() : undefined);
+        },
+        acquireLock: () => acquireLock(),
+        install: (spec) => spawnNpmSync(inv, ["install", "-g", "--no-fund", "--no-audit", spec], {
+            stdio: ["ignore", 2, 2],
+            timeout: 5 * 60 * 1000,
+        }).ok,
+        write: (chunk) => void process.stderr.write(chunk),
+    };
+}