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

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

@@ -0,0 +1,54 @@
+/**
+ * One update pass — shared by the detached background worker and the
+ * foreground `mnemom update` command. Pure orchestration over injected deps:
+ * fetch dist-tags → resolve the `next` entitlement → pick a target → decide →
+ * (maybe) install → persist state. Never throws; failures become state
+ * (backoff) and a result the caller may print.
+ */
+import { type DistTags, type InstallMethod, type ResolvedSettings, type UpdateAction, type UpdateChannel, type UpdateState } from "./decide.js";
+import type { EntitlementResult } from "./registry.js";
+export type InstallResult = {
+    ok: true;
+} | {
+    ok: false;
+    eacces: boolean;
+    message: string;
+};
+export interface RunDeps {
+    current: string;
+    now(): number;
+    loadState(): UpdateState;
+    saveState(patch: Partial<UpdateState>): void;
+    fetchDistTags(): Promise<DistTags>;
+    fetchEntitlement(): Promise<EntitlementResult>;
+    installMethod(): Promise<InstallMethod>;
+    install(version: string): Promise<InstallResult>;
+    /**
+     * Gate before installing: the background worker waits here for the CLI
+     * process that spawned it to exit (never swap files under a live
+     * `mnemom agent` session). Resolving false skips the install this pass.
+     */
+    beforeInstall?(): Promise<boolean>;
+}
+export interface RunResult {
+    /** The channel actually honoured (next falls back to latest when not entitled). */
+    channel: UpdateChannel;
+    /** True when `next` was requested but not honoured. */
+    channelDowngraded: boolean;
+    method?: InstallMethod;
+    target?: string;
+    action?: UpdateAction;
+    installed?: string;
+    error?: string;
+}
+/**
+ * Resolve the `next` entitlement: a fresh cache wins; otherwise ask the API.
+ * A definitive answer is cached; "unavailable" falls back to any cached value
+ * (stale is better than flapping a paying customer off their channel during an
+ * API blip); "unauthenticated" is simply not entitled.
+ */
+export declare function resolveEntitlement(deps: Pick<RunDeps, "fetchEntitlement" | "saveState">, state: UpdateState, now: number): Promise<boolean>;
+export declare function runUpdate(deps: RunDeps, settings: ResolvedSettings, opts?: {
+    force?: boolean;
+    foreground?: boolean;
+}): Promise<RunResult>;

package/dist/lib/update/run.js

@@ -0,0 +1,100 @@
+/**
+ * One update pass — shared by the detached background worker and the
+ * foreground `mnemom update` command. Pure orchestration over injected deps:
+ * fetch dist-tags → resolve the `next` entitlement → pick a target → decide →
+ * (maybe) install → persist state. Never throws; failures become state
+ * (backoff) and a result the caller may print.
+ */
+import { backoffDelay, decide, effectiveChannel, entitlementFresh, pickTarget, } from "./decide.js";
+import { compareVersions } from "./semver.js";
+/**
+ * Resolve the `next` entitlement: a fresh cache wins; otherwise ask the API.
+ * A definitive answer is cached; "unavailable" falls back to any cached value
+ * (stale is better than flapping a paying customer off their channel during an
+ * API blip); "unauthenticated" is simply not entitled.
+ */
+export async function resolveEntitlement(deps, state, now) {
+    const cached = state.entitlement;
+    if (cached && entitlementFresh(cached, now))
+        return cached.next;
+    const res = await deps.fetchEntitlement();
+    if (res === "unauthenticated")
+        return false;
+    if (res === "unavailable")
+        return state.entitlement?.next ?? false;
+    deps.saveState({ entitlement: { next: res.next, checkedAt: now } });
+    return res.next;
+}
+function failurePatch(state, now, message) {
+    const failures = (state.failures ?? 0) + 1;
+    return {
+        failures,
+        backoffUntil: now + backoffDelay(failures),
+        lastError: message,
+        lastCheck: now,
+    };
+}
+export async function runUpdate(deps, settings, opts = {}) {
+    const now = deps.now();
+    const state = deps.loadState();
+    let tags;
+    try {
+        tags = await deps.fetchDistTags();
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        deps.saveState(failurePatch(state, now, message));
+        return { channel: settings.channel, channelDowngraded: false, error: message };
+    }
+    const entitled = settings.channel === "next" ? await resolveEntitlement(deps, state, now) : false;
+    const channel = effectiveChannel(settings.channel, entitled);
+    const channelDowngraded = channel !== settings.channel;
+    const target = pickTarget(tags, channel);
+    const method = await deps.installMethod();
+    const action = decide({
+        current: deps.current,
+        target,
+        mode: settings.mode,
+        method,
+        // An explicit `mnemom update` retries even after an EACCES (the user may have fixed it).
+        installBlocked: opts.foreground ? false : state.installBlocked,
+        force: opts.force,
+    });
+    const newer = target !== undefined && compareVersions(target, deps.current) > 0;
+    const base = {
+        lastCheck: now,
+        method,
+        available: newer ? target : undefined,
+        failures: undefined,
+        backoffUntil: undefined,
+        lastError: undefined,
+    };
+    const result = { channel, channelDowngraded, method, target, action };
+    if (action.kind !== "install") {
+        deps.saveState(base);
+        return result;
+    }
+    const proceed = deps.beforeInstall ? await deps.beforeInstall() : true;
+    if (!proceed) {
+        deps.saveState(base);
+        return { ...result, action: { kind: "notify", version: action.version, reason: "deferred" } };
+    }
+    const outcome = await deps.install(action.version);
+    if (outcome.ok) {
+        deps.saveState({
+            ...base,
+            available: undefined,
+            installBlocked: undefined,
+            pending: { from: deps.current, to: action.version, channel },
+        });
+        return { ...result, installed: action.version };
+    }
+    if (outcome.eacces) {
+        // Retrying can't fix permissions — switch to notify-with-instructions.
+        deps.saveState({ ...base, installBlocked: true, lastError: outcome.message });
+    }
+    else {
+        deps.saveState({ ...failurePatch(state, now, outcome.message), available: base.available });
+    }
+    return { ...result, error: outcome.message };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Minimal SemVer 2.0 precedence for auto-update decisions.
+ *
+ * `lib/version-gate.ts#isBelowVersion` deliberately IGNORES prerelease tags (a
+ * `-rc` of a good release passes the server floor). Auto-update needs the
+ * opposite: `0.17.2-next.3 < 0.17.2 < 0.17.3-next.0` must order correctly so a
+ * `next` user moves onto the stable cut and a `latest` user never regresses.
+ * Build metadata (`+…`) is ignored, per spec.
+ */
+interface Parsed {
+    core: [number, number, number];
+    pre: string[];
+}
+export declare function parseVersion(v: string): Parsed | null;
+export declare function isValidVersion(v: string): boolean;
+export declare function isPrerelease(v: string): boolean;
+/**
+ * -1 / 0 / 1 by SemVer precedence. Throws on an unparseable version — callers
+ * validate registry input with `isValidVersion` first.
+ */
+export declare function compareVersions(a: string, b: string): number;
+export {};

package/dist/lib/update/semver.js

@@ -0,0 +1,65 @@
+/**
+ * Minimal SemVer 2.0 precedence for auto-update decisions.
+ *
+ * `lib/version-gate.ts#isBelowVersion` deliberately IGNORES prerelease tags (a
+ * `-rc` of a good release passes the server floor). Auto-update needs the
+ * opposite: `0.17.2-next.3 < 0.17.2 < 0.17.3-next.0` must order correctly so a
+ * `next` user moves onto the stable cut and a `latest` user never regresses.
+ * Build metadata (`+…`) is ignored, per spec.
+ */
+const VERSION_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+export function parseVersion(v) {
+    const m = VERSION_RE.exec(v.trim());
+    if (!m)
+        return null;
+    return {
+        core: [Number(m[1]), Number(m[2]), Number(m[3])],
+        pre: m[4] ? m[4].split(".") : [],
+    };
+}
+export function isValidVersion(v) {
+    return parseVersion(v) !== null;
+}
+export function isPrerelease(v) {
+    return (parseVersion(v)?.pre.length ?? 0) > 0;
+}
+function compareIdent(a, b) {
+    const an = /^\d+$/.test(a);
+    const bn = /^\d+$/.test(b);
+    if (an && bn)
+        return Math.sign(Number(a) - Number(b));
+    // Numeric identifiers always have lower precedence than alphanumeric ones.
+    if (an !== bn)
+        return an ? -1 : 1;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * -1 / 0 / 1 by SemVer precedence. Throws on an unparseable version — callers
+ * validate registry input with `isValidVersion` first.
+ */
+export function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    if (!pa || !pb)
+        throw new Error(`invalid version: ${!pa ? a : b}`);
+    for (let i = 0; i < 3; i++) {
+        if (pa.core[i] !== pb.core[i])
+            return Math.sign(pa.core[i] - pb.core[i]);
+    }
+    // A release outranks any prerelease of the same core.
+    if (pa.pre.length === 0 || pb.pre.length === 0) {
+        return Math.sign(pb.pre.length - pa.pre.length);
+    }
+    const len = Math.max(pa.pre.length, pb.pre.length);
+    for (let i = 0; i < len; i++) {
+        // A shorter identifier list is lower precedence when all shared ones match.
+        if (pa.pre[i] === undefined)
+            return -1;
+        if (pb.pre[i] === undefined)
+            return 1;
+        const c = compareIdent(pa.pre[i], pb.pre[i]);
+        if (c !== 0)
+            return c;
+    }
+    return 0;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * The per-invocation hook, run before commander parses argv. It must cost
+ * ~nothing and never fail the user's command:
+ *   1. print a one-line stderr notice (completed update, or an available one);
+ *   2. if a check is due, spawn the detached worker and return immediately.
+ * All I/O is injected; `defaultStartupDeps()` wires the real process.
+ */
+import { type UpdateChannel, type UpdateMode, type UpdatePrefs, type UpdateState } from "./decide.js";
+export interface StartupDeps {
+    current: string;
+    argv: string[];
+    env: Record<string, string | undefined>;
+    stdoutTTY: boolean;
+    stderrTTY: boolean;
+    now(): number;
+    prefs(): UpdatePrefs;
+    loadState(): UpdateState;
+    saveState(patch: Partial<UpdateState>): void;
+    entryPath: string;
+    writeErr(line: string): void;
+    spawnWorker(args: [entry: string, channel: UpdateChannel, mode: UpdateMode, parentPid: string]): void;
+    pid: number;
+}
+export declare function maybeRunUpdateHook(deps: StartupDeps): void;
+/** dist/lib/update/startup.js → dist/update-worker.js */
+export declare const WORKER_PATH: string;
+export declare function defaultStartupDeps(argv: string[]): StartupDeps;

package/dist/lib/update/startup.js

@@ -0,0 +1,75 @@
+/**
+ * The per-invocation hook, run before commander parses argv. It must cost
+ * ~nothing and never fail the user's command:
+ *   1. print a one-line stderr notice (completed update, or an available one);
+ *   2. if a check is due, spawn the detached worker and return immediately.
+ * All I/O is injected; `defaultStartupDeps()` wires the real process.
+ */
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { CLI_VERSION } from "../../version.js";
+import { resolveSettings, shouldCheck, startupNotice, } from "./decide.js";
+import { classifyInstall } from "./install-method.js";
+import { loadUpdateState, saveUpdateState } from "./state.js";
+import { entryRealpath, loadUpdatePrefs } from "./system.js";
+/** Commands that manage updates themselves, or must stay side-effect free. */
+const SKIP_COMMANDS = new Set(["update", "config"]);
+export function maybeRunUpdateHook(deps) {
+    try {
+        const settings = resolveSettings({ prefs: deps.prefs(), env: deps.env, isTTY: deps.stdoutTTY });
+        if (settings.mode === "off")
+            return;
+        if (classifyInstall(deps.entryPath, undefined) === "dev")
+            return;
+        const now = deps.now();
+        const state = deps.loadState();
+        const notice = startupNotice({
+            current: deps.current,
+            state,
+            mode: settings.mode,
+            method: state.method ?? "unknown",
+            now,
+        });
+        if (notice && deps.stderrTTY && !deps.argv.includes("--json")) {
+            deps.writeErr(`${notice.message}\n`);
+            deps.saveState(notice.patch);
+        }
+        if (SKIP_COMMANDS.has(deps.argv[0] ?? ""))
+            return;
+        if (!shouldCheck(state, settings.channel, now))
+            return;
+        // Stamp first so a burst of commands doesn't spawn a burst of workers.
+        deps.saveState({ lastCheck: now });
+        deps.spawnWorker([deps.entryPath, settings.channel, settings.mode, String(deps.pid)]);
+    }
+    catch {
+        /* the updater never breaks the user's command */
+    }
+}
+/** dist/lib/update/startup.js → dist/update-worker.js */
+export const WORKER_PATH = fileURLToPath(new URL("../../update-worker.js", import.meta.url));
+export function defaultStartupDeps(argv) {
+    return {
+        current: CLI_VERSION,
+        argv,
+        env: process.env,
+        stdoutTTY: process.stdout.isTTY === true,
+        stderrTTY: process.stderr.isTTY === true,
+        now: Date.now,
+        prefs: loadUpdatePrefs,
+        loadState: () => loadUpdateState(),
+        saveState: (patch) => saveUpdateState(patch),
+        entryPath: entryRealpath(process.argv[1]),
+        pid: process.pid,
+        writeErr: (line) => void process.stderr.write(line),
+        spawnWorker: (args) => {
+            const child = spawn(process.execPath, [WORKER_PATH, ...args], {
+                detached: true,
+                stdio: "ignore",
+                windowsHide: true,
+            });
+            child.on("error", () => { });
+            child.unref();
+        },
+    };
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Persistence for the updater: ~/.mnemom/update-state.json (throttle, backoff,
+ * pending notice, entitlement cache) and ~/.mnemom/update.lock (one installer
+ * at a time across every open terminal).
+ *
+ * Every failure here degrades silently — the updater must never break the
+ * command the user actually ran.
+ */
+import type { UpdateState } from "./decide.js";
+/** A lock older than this is from a crashed worker and may be taken over. */
+export declare const LOCK_STALE_MS: number;
+export declare function stateFile(dir?: string): string;
+export declare function lockFile(dir?: string): string;
+/** Missing, unreadable or corrupt → `{}` (read-and-catch; no exists-then-read race). */
+export declare function loadUpdateState(dir?: string): UpdateState;
+/** Merge `patch` into the stored state (undefined values delete keys); atomic write. */
+export declare function saveUpdateState(patch: Partial<UpdateState>, dir?: string): void;
+/**
+ * Take the install lock with O_EXCL. A lock older than LOCK_STALE_MS is removed
+ * and retried once. Returns a release function, or null if another live
+ * process holds it.
+ */
+export declare function acquireLock(dir?: string, now?: number): (() => void) | null;

package/dist/lib/update/state.js

@@ -0,0 +1,83 @@
+/**
+ * Persistence for the updater: ~/.mnemom/update-state.json (throttle, backoff,
+ * pending notice, entitlement cache) and ~/.mnemom/update.lock (one installer
+ * at a time across every open terminal).
+ *
+ * Every failure here degrades silently — the updater must never break the
+ * command the user actually ran.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { MNEMOM_DIR } from "../config.js";
+/** A lock older than this is from a crashed worker and may be taken over. */
+export const LOCK_STALE_MS = 10 * 60 * 1000;
+export function stateFile(dir = MNEMOM_DIR) {
+    return path.join(dir, "update-state.json");
+}
+export function lockFile(dir = MNEMOM_DIR) {
+    return path.join(dir, "update.lock");
+}
+/** Missing, unreadable or corrupt → `{}` (read-and-catch; no exists-then-read race). */
+export function loadUpdateState(dir = MNEMOM_DIR) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(stateFile(dir), "utf-8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Merge `patch` into the stored state (undefined values delete keys); atomic write. */
+export function saveUpdateState(patch, dir = MNEMOM_DIR) {
+    try {
+        const merged = { ...loadUpdateState(dir), ...patch };
+        const next = Object.fromEntries(Object.entries(merged).filter(([, v]) => v !== undefined));
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const tmp = `${stateFile(dir)}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
+        fs.renameSync(tmp, stateFile(dir));
+    }
+    catch {
+        /* best effort */
+    }
+}
+/**
+ * Take the install lock with O_EXCL. A lock older than LOCK_STALE_MS is removed
+ * and retried once. Returns a release function, or null if another live
+ * process holds it.
+ */
+export function acquireLock(dir = MNEMOM_DIR, now = Date.now()) {
+    const file = lockFile(dir);
+    const tryCreate = () => {
+        try {
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+            fs.writeFileSync(file, String(process.pid), { flag: "wx", mode: 0o600 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (!tryCreate()) {
+        try {
+            if (now - fs.statSync(file).mtimeMs < LOCK_STALE_MS)
+                return null;
+            fs.rmSync(file, { force: true });
+        }
+        catch {
+            return null;
+        }
+        if (!tryCreate())
+            return null;
+    }
+    return () => {
+        try {
+            fs.rmSync(file, { force: true });
+        }
+        catch {
+            /* best effort */
+        }
+    };
+}

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

@@ -0,0 +1,55 @@
+/**
+ * The real-world side of the updater: spawn npm, read credentials, read prefs.
+ * Each function takes its process-level dependencies as injectable parameters
+ * so the branches are testable without touching the machine.
+ */
+import { resolveAuth } from "../auth.js";
+import { type UpdatePrefs } from "./decide.js";
+import type { ApiCredential } from "./registry.js";
+import type { InstallResult } from "./run.js";
+export declare const INSTALL_TIMEOUT_MS: number;
+type ExecFile = (file: string, args: string[], opts: {
+    timeout: number;
+    windowsHide: boolean;
+}, cb: (err: (Error & {
+    code?: unknown;
+}) | null, stdout: string, stderr: string) => void) => unknown;
+/** How to run npm WITHOUT a shell: the program plus any leading args. */
+export interface NpmInvocation {
+    file: string;
+    prefix: string[];
+}
+/**
+ * Never `shell: true` (npm's registry-/header-derived arguments must not reach
+ * a shell). POSIX runs `npm` directly. On Windows `npm` is a `.cmd` shim that
+ * can't be spawned without a shell, so run the npm CLI script with this node
+ * binary instead — it ships beside node.exe in every standard Windows install.
+ * No such script → null, and the caller treats npm as unavailable (notify only).
+ */
+export declare function npmInvocation(platform?: NodeJS.Platform, execPath?: string, exists?: (p: string) => boolean): NpmInvocation | null;
+/** `npm root -g`, or undefined when npm isn't available / fails. */
+export declare function npmGlobalRoot(execFile?: ExecFile, inv?: NpmInvocation | null): Promise<string | undefined>;
+/** Permission failures can't be fixed by retrying — the caller switches to notify. */
+export declare function isPermissionError(text: string): boolean;
+/**
+ * `npm install -g @mnemom/mnemom@<exact version>` — exact, never a tag (no
+ * tag-move race). The version is re-validated here, at the sink, even though
+ * `pickTarget` already filtered it.
+ */
+export declare function npmInstallGlobal(version: string, execFile?: ExecFile, inv?: NpmInvocation | null): Promise<InstallResult>;
+/** realpath of the entry script (the global bin is a symlink); falls back to the raw path. */
+export declare function entryRealpath(argv1: string | undefined, realpath?: (p: string) => string): string;
+/**
+ * Credential for the BACKGROUND worker. Deliberately never refreshes: a
+ * detached refresh racing a foreground command could rotate the refresh token
+ * out from under it. An expired stored token just means "unauthenticated" for
+ * this pass (the cached entitlement still applies).
+ */
+export declare function backgroundCredential(env?: Record<string, string | undefined>, auth?: {
+    accessToken: string;
+    expiresAt: number;
+} | null, nowSec?: number): ApiCredential;
+/** Credential for the FOREGROUND `mnemom update` — normal resolution, refresh allowed. */
+export declare function foregroundCredential(resolve?: typeof resolveAuth): Promise<ApiCredential>;
+export declare function loadUpdatePrefs(): UpdatePrefs;
+export {};

package/dist/lib/update/system.js

@@ -0,0 +1,104 @@
+/**
+ * The real-world side of the updater: spawn npm, read credentials, read prefs.
+ * Each function takes its process-level dependencies as injectable parameters
+ * so the branches are testable without touching the machine.
+ */
+import { execFile as nodeExecFile } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { win32 } from "node:path";
+import { getAuthInfo, resolveAuth } from "../auth.js";
+import { loadCliConfig } from "../cli-config.js";
+import { PACKAGE_NAME } from "./decide.js";
+import { isValidVersion } from "./semver.js";
+export const INSTALL_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * Never `shell: true` (npm's registry-/header-derived arguments must not reach
+ * a shell). POSIX runs `npm` directly. On Windows `npm` is a `.cmd` shim that
+ * can't be spawned without a shell, so run the npm CLI script with this node
+ * binary instead — it ships beside node.exe in every standard Windows install.
+ * No such script → null, and the caller treats npm as unavailable (notify only).
+ */
+export function npmInvocation(platform = process.platform, execPath = process.execPath, exists = existsSync) {
+    if (platform !== "win32")
+        return { file: "npm", prefix: [] };
+    const cli = win32.join(win32.dirname(execPath), "node_modules", "npm", "bin", "npm-cli.js");
+    return exists(cli) ? { file: execPath, prefix: [cli] } : null;
+}
+function run(inv, args, timeout, execFile) {
+    return new Promise((resolve) => {
+        execFile(inv.file, [...inv.prefix, ...args], { timeout, windowsHide: true }, (err, stdout, stderr) => resolve({ err, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") }));
+    });
+}
+/** `npm root -g`, or undefined when npm isn't available / fails. */
+export async function npmGlobalRoot(execFile = nodeExecFile, inv = npmInvocation()) {
+    if (!inv)
+        return undefined;
+    const { err, stdout } = await run(inv, ["root", "-g"], 15_000, execFile);
+    const root = stdout.trim();
+    return err || !root ? undefined : root;
+}
+/** Permission failures can't be fixed by retrying — the caller switches to notify. */
+export function isPermissionError(text) {
+    return /\bE(ACCES|PERM)\b/.test(text);
+}
+/**
+ * `npm install -g @mnemom/mnemom@<exact version>` — exact, never a tag (no
+ * tag-move race). The version is re-validated here, at the sink, even though
+ * `pickTarget` already filtered it.
+ */
+export async function npmInstallGlobal(version, execFile = nodeExecFile, inv = npmInvocation()) {
+    if (!isValidVersion(version)) {
+        return {
+            ok: false,
+            eacces: false,
+            message: `refusing to install invalid version '${version}'`,
+        };
+    }
+    if (!inv)
+        return { ok: false, eacces: false, message: "npm is not available" };
+    const { err, stderr } = await run(inv, ["install", "-g", "--no-fund", "--no-audit", `${PACKAGE_NAME}@${version}`], INSTALL_TIMEOUT_MS, execFile);
+    if (!err)
+        return { ok: true };
+    const detail = `${err.message}\n${stderr}`;
+    const lastLine = stderr.trim().split("\n").pop() || err.message;
+    return { ok: false, eacces: isPermissionError(detail), message: lastLine.slice(0, 300) };
+}
+/** realpath of the entry script (the global bin is a symlink); falls back to the raw path. */
+export function entryRealpath(argv1, realpath = realpathSync) {
+    if (!argv1)
+        return "";
+    try {
+        return realpath(argv1);
+    }
+    catch {
+        return argv1;
+    }
+}
+/**
+ * Credential for the BACKGROUND worker. Deliberately never refreshes: a
+ * detached refresh racing a foreground command could rotate the refresh token
+ * out from under it. An expired stored token just means "unauthenticated" for
+ * this pass (the cached entitlement still applies).
+ */
+export function backgroundCredential(env = process.env, auth = getAuthInfo(), nowSec = Math.floor(Date.now() / 1000)) {
+    if (env.MNEMOM_TOKEN)
+        return { name: "Authorization", value: `Bearer ${env.MNEMOM_TOKEN}` };
+    if (auth && auth.expiresAt > nowSec + 60) {
+        return { name: "Authorization", value: `Bearer ${auth.accessToken}` };
+    }
+    if (env.MNEMOM_API_KEY)
+        return { name: "X-Mnemom-Api-Key", value: env.MNEMOM_API_KEY };
+    return null;
+}
+/** Credential for the FOREGROUND `mnemom update` — normal resolution, refresh allowed. */
+export async function foregroundCredential(resolve = resolveAuth) {
+    const cred = await resolve();
+    if (cred.type === "jwt")
+        return { name: "Authorization", value: `Bearer ${cred.token}` };
+    if (cred.type === "api-key")
+        return { name: "X-Mnemom-Api-Key", value: cred.key };
+    return null;
+}
+export function loadUpdatePrefs() {
+    return loadCliConfig().update ?? {};
+}

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

@@ -0,0 +1,42 @@
+/**
+ * The detached background worker (entry: src/update-worker.ts) and the real
+ * `RunDeps` wiring shared with `mnemom update`.
+ *
+ * The parent passes the settings it resolved (`<entry> <channel> <mode> <pid>`): the
+ * worker runs with stdio ignored, so re-resolving here would always see a
+ * non-TTY and force `off`.
+ */
+import { type ResolvedSettings } from "./decide.js";
+import { type ApiCredential } from "./registry.js";
+import { type InstallResult, type RunDeps, type RunResult } from "./run.js";
+export interface WorkerArgs {
+    entry: string;
+    settings: ResolvedSettings;
+    /** The CLI process that spawned us; installs wait until it has exited. */
+    parentPid?: number;
+}
+export declare function parseWorkerArgs(args: string[]): WorkerArgs | null;
+export declare const PARENT_POLL_MS = 5000;
+/** Give up waiting on a very long session; the next run picks the update up. */
+export declare const PARENT_WAIT_MAX_MS: number;
+/** `kill(pid, 0)` probes liveness without signalling. EPERM still means alive. */
+export declare function isAlive(pid: number, kill?: (pid: number, sig: 0) => void): boolean;
+/** Resolve true once `pid` is gone, false if it outlives `maxMs`. */
+export declare function waitForExit(pid: number | undefined, deps?: {
+    alive(pid: number): boolean;
+    sleep(ms: number): Promise<void>;
+    now(): number;
+}, maxMs?: number): Promise<boolean>;
+export declare function realRunDeps(entry: string, credential: () => ApiCredential | Promise<ApiCredential>): RunDeps;
+/**
+ * The install lock is held ONLY around `npm install` — never while waiting for
+ * the parent to exit (a 12h wait would look stale at LOCK_STALE_MS and let a
+ * second installer in). Lock busy → skip this pass; the other installer wins.
+ */
+export declare function lockedInstall(parentPid: number | undefined, deps: {
+    waitForExit(pid: number | undefined): Promise<boolean>;
+    acquireLock(): (() => void) | null;
+    install(version: string): Promise<InstallResult>;
+}): Pick<RunDeps, "beforeInstall" | "install">;
+export declare function runWorker(args: string[], run: (args: WorkerArgs) => Promise<RunResult>): Promise<"bad-args" | RunResult>;
+export declare function defaultWorkerRun(credential: () => ApiCredential): (args: WorkerArgs) => Promise<RunResult>;