agent-dealer 0.1.13 → 0.3.0

package/bundle/shared/dist/runtime.d.ts

@@ -1,3 +1,3 @@
 import { z } from "zod";
-export declare const Runtime: z.ZodEnum<["claude_code", "cursor_local"]>;
+export declare const Runtime: z.ZodEnum<["claude_code", "cursor_local", "codex_local"]>;
 export type Runtime = z.infer<typeof Runtime>;

package/bundle/shared/dist/runtime.js

@@ -1,2 +1,2 @@
 import { z } from "zod";
-export const Runtime = z.enum(["claude_code", "cursor_local"]);
+export const Runtime = z.enum(["claude_code", "cursor_local", "codex_local"]);

package/bundle/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dealer/shared",
-  "version": "0.1.13",
+  "version": "0.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/dist/doctor.js

@@ -4,6 +4,8 @@ import { claudeAvailable } from "./cli-check.js";
 import { loadProdEnvFile, prodEnvFilePath, prodHomeDir, resolveBundledListenPort, shortenHome, } from "./env.js";
 import { probeAgentDealer } from "./ports.js";
 import { resolveServerEntry, resolveUiDist } from "./paths.js";
+import { detectInstallKind, localBinLauncherPath, readCurrentManagedVersion, readUpdateState, resolveCurrentVersionDir, } from "./managed/index.js";
+import { getVersion } from "./version.js";
 export async function runDoctor() {
     let failed = false;
     const major = Number(process.versions.node.split(".")[0]);
@@ -53,6 +55,22 @@ export async function runDoctor() {
     if (fs.existsSync(home)) {
         console.log(`✓ data ${shortenHome(home)}`);
     }
+    console.log(`Package version ${getVersion()}`);
+    const kind = detectInstallKind();
+    console.log(`Install kind: ${kind}`);
+    if (kind === "managed") {
+        const current = readCurrentManagedVersion();
+        const currentDir = resolveCurrentVersionDir();
+        console.log(`Managed current: ${current ?? "(unknown)"} (${currentDir ?? "missing"})`);
+        console.log(`Launcher: ${localBinLauncherPath()}`);
+        const pending = readUpdateState()?.pendingVersion;
+        if (pending) {
+            console.log(`Pending managed version: ${pending} (activates on next start/doctor/upgrade)`);
+        }
+    }
+    else {
+        console.log("Tip: agent-dealer install  # managed CLI + auto-updates (data unchanged)");
+    }
     const port = resolveBundledListenPort();
     const probe = await probeAgentDealer("127.0.0.1", port);
     if (probe.up) {

package/dist/index.js

@@ -6,6 +6,7 @@ import { runStop } from "./stop.js";
 import { maybeCheckForUpdateOnRun } from "./update-check.js";
 import { getVersion } from "./version.js";
 import { runUpgrade, printUpgradeHelp } from "./upgrade.js";
+import { runInstall, printInstallHelp } from "./install.js";
 function printUsage() {
     console.log(`Usage:
   agent-dealer setup [--home DIR] [--force]
@@ -13,7 +14,8 @@ function printUsage() {
   agent-dealer stop
   agent-dealer status
   agent-dealer doctor
-  agent-dealer upgrade [--to VERSION] [--yes]
+  agent-dealer install [--to VERSION] [--migrate-cli] [--purge-global]
+  agent-dealer upgrade [--to VERSION] [--yes] [--check]
   agent-dealer --version
 
 Human control plane for agent execution.`);
@@ -92,6 +94,13 @@ export async function runCli(argv) {
             return 0;
         return runDoctor();
     }
+    if (cmd === "install") {
+        if (args.includes("--help")) {
+            printInstallHelp();
+            return 0;
+        }
+        return runInstall(args.slice(1));
+    }
     if (cmd === "upgrade") {
         if (args.includes("--help")) {
             printUpgradeHelp();
@@ -99,17 +108,20 @@ export async function runCli(argv) {
         }
         let toVersion;
         let yes = false;
+        let check = false;
         for (let i = 1; i < args.length; i += 1) {
             if (args[i] === "--to")
                 toVersion = args[++i];
             else if (args[i] === "--yes")
                 yes = true;
+            else if (args[i] === "--check")
+                check = true;
             else {
                 console.error(`Unknown upgrade option: ${args[i]}`);
                 return 1;
             }
         }
-        return runUpgrade({ toVersion, yes });
+        return runUpgrade({ toVersion, yes, check });
     }
     console.error(`Unknown command: ${cmd}`);
     printUsage();

package/dist/install.d.ts

@@ -0,0 +1,8 @@
+import { installCliVersionToPrefix } from "./managed/index.js";
+export type InstallDeps = {
+    installVersion?: typeof installCliVersionToPrefix;
+    fetchLatest?: () => Promise<string | null>;
+    purgeGlobal?: () => Promise<number>;
+};
+export declare function printInstallHelp(): void;
+export declare function runInstall(args: string[], deps?: InstallDeps): Promise<number>;

package/dist/install.js

@@ -0,0 +1,72 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { activateVersion, cliEntryInVersionDir, fetchLatestVersion, installCliVersionToPrefix, localBinLauncherPath, PACKAGE_NAME, versionDir, } from "./managed/index.js";
+function parseArgs(args) {
+    let to;
+    let migrateCli = false;
+    let purgeGlobal = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === "--to")
+            to = args[++i];
+        else if (a === "--migrate-cli")
+            migrateCli = true;
+        else if (a === "--purge-global")
+            purgeGlobal = true;
+    }
+    return { to, migrateCli, purgeGlobal };
+}
+export function printInstallHelp() {
+    console.log(`Usage:
+  agent-dealer install [--to VERSION] [--migrate-cli] [--purge-global]
+
+Installs agent-dealer into ~/.agent-dealer/versions and writes ~/.local/bin/agent-dealer.
+Existing config, queue data, and logs are left unchanged.`);
+}
+export async function runInstall(args, deps = {}) {
+    if (args.includes("--help") || args.includes("-h")) {
+        printInstallHelp();
+        return 0;
+    }
+    const { to, migrateCli, purgeGlobal } = parseArgs(args);
+    const fetchLatest = deps.fetchLatest ?? fetchLatestVersion;
+    const installVersion = deps.installVersion ?? installCliVersionToPrefix;
+    const version = to ?? (await fetchLatest());
+    if (!version) {
+        console.error("Could not resolve latest version from npm.");
+        return 1;
+    }
+    if (!fs.existsSync(cliEntryInVersionDir(versionDir(version)))) {
+        const result = await installVersion(version);
+        if (!result.ok) {
+            console.error(`Managed install failed: ${result.error}`);
+            return 1;
+        }
+    }
+    activateVersion(version);
+    const home = process.env.AGENT_DEALER_HOME?.trim() || path.join(os.homedir(), ".agent-dealer");
+    console.log(`Installed ${PACKAGE_NAME}@${version} to ${home} (data home unchanged).`);
+    console.log(`Launcher: ${localBinLauncherPath()}`);
+    console.log('If command not found: export PATH="$HOME/.local/bin:$PATH"');
+    if (migrateCli) {
+        console.log("Prefer ~/.local/bin ahead of any npm global agent-dealer on PATH.");
+    }
+    console.log("Next: agent-dealer doctor && agent-dealer start --daemon --open");
+    if (purgeGlobal) {
+        const code = deps.purgeGlobal
+            ? await deps.purgeGlobal()
+            : await new Promise((resolve) => {
+                const child = spawn("npm", ["uninstall", "-g", PACKAGE_NAME], {
+                    stdio: "inherit",
+                    shell: process.platform === "win32",
+                });
+                child.on("exit", (c) => resolve(c ?? 1));
+            });
+        if (code !== 0) {
+            console.warn("Warning: could not uninstall npm global package (managed install is still active).");
+        }
+    }
+    return 0;
+}

package/dist/managed/activate.d.ts

@@ -0,0 +1,2 @@
+export declare function activateVersion(version: string): void;
+export declare function pruneOldVersions(keep: number): void;

package/dist/managed/activate.js

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import path from "node:path";
+import { writeLocalBinLauncher } from "./launcher.js";
+import { cliEntryInVersionDir, currentLinkPath, resolveCurrentVersionDir, versionDir, versionsDir, } from "./paths.js";
+import { compareSemver } from "./semver.js";
+export function activateVersion(version) {
+    const target = versionDir(version);
+    const entry = cliEntryInVersionDir(target);
+    if (!fs.existsSync(entry)) {
+        throw new Error(`Cannot activate ${version}: missing ${entry}`);
+    }
+    const link = currentLinkPath();
+    fs.mkdirSync(path.dirname(link), { recursive: true });
+    try {
+        const st = fs.lstatSync(link);
+        if (st.isSymbolicLink() || st.isFile()) {
+            fs.unlinkSync(link);
+        }
+        else {
+            fs.rmSync(link, { recursive: true, force: true });
+        }
+    }
+    catch {
+        // missing
+    }
+    fs.symlinkSync(target, link, "dir");
+    writeLocalBinLauncher();
+    pruneOldVersions(3);
+}
+export function pruneOldVersions(keep) {
+    const root = versionsDir();
+    if (!fs.existsSync(root))
+        return;
+    const currentReal = resolveCurrentVersionDir();
+    const names = fs
+        .readdirSync(root, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && !d.name.startsWith("."))
+        .map((d) => d.name)
+        .sort((a, b) => compareSemver(b, a));
+    const retained = names.slice(0, Math.max(keep, 0));
+    for (const name of names) {
+        const full = path.join(root, name);
+        if (retained.includes(name))
+            continue;
+        if (currentReal && fs.existsSync(full) && fs.realpathSync(full) === currentReal)
+            continue;
+        fs.rmSync(full, { recursive: true, force: true });
+    }
+}

package/dist/managed/activate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/managed/activate.test.js

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { activateVersion } from "./activate.js";
+import { detectInstallKind } from "./install-kind.js";
+import { currentLinkPath, localBinLauncherPath, versionDir } from "./paths.js";
+function seedVersion(ver) {
+    const dir = versionDir(ver);
+    const bin = path.join(dir, "node_modules", "agent-dealer", "dist", "bin.js");
+    fs.mkdirSync(path.dirname(bin), { recursive: true });
+    fs.writeFileSync(bin, "ok\n");
+}
+test("managed activate preserves sibling data and writes launcher", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "adlr-act-"));
+    const localBin = path.join(tmp, "local-bin");
+    process.env.AGENT_DEALER_HOME = tmp;
+    process.env.AGENT_DEALER_LOCAL_BIN = localBin;
+    try {
+        fs.writeFileSync(path.join(tmp, ".env"), "KEEP=1\n");
+        seedVersion("0.1.0");
+        activateVersion("0.1.0");
+        assert.equal(fs.realpathSync(currentLinkPath()), fs.realpathSync(versionDir("0.1.0")));
+        assert.equal(fs.readFileSync(path.join(tmp, ".env"), "utf8"), "KEEP=1\n");
+        assert.ok(fs.existsSync(localBinLauncherPath()));
+        assert.equal(detectInstallKind(), "managed");
+    }
+    finally {
+        delete process.env.AGENT_DEALER_HOME;
+        delete process.env.AGENT_DEALER_LOCAL_BIN;
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+});

package/dist/managed/index.d.ts

@@ -0,0 +1,8 @@
+export { agentDealerHome, cliEntryInVersionDir, currentLinkPath, localBinDir, localBinLauncherPath, partialVersionDir, resolveCurrentVersionDir, updateStatePath, versionDir, versionsDir, } from "./paths.js";
+export { detectInstallKind, type InstallKind } from "./install-kind.js";
+export { activateVersion, pruneOldVersions } from "./activate.js";
+export { writeLocalBinLauncher } from "./launcher.js";
+export { installCliVersionToPrefix, PACKAGE_NAME } from "./npm-prefix-install.js";
+export { compareSemver } from "./semver.js";
+export { readUpdateState, writeUpdateState, type UpdateState } from "./update-state.js";
+export { ensurePendingDownload, fetchLatestVersion, isAutoupdaterDisabled, maybeActivatePendingVersion, readCurrentManagedVersion, runManagedCliEntryHooks, scheduleBackgroundUpdateCheck, } from "./updater.js";

package/dist/managed/index.js

@@ -0,0 +1,8 @@
+export { agentDealerHome, cliEntryInVersionDir, currentLinkPath, localBinDir, localBinLauncherPath, partialVersionDir, resolveCurrentVersionDir, updateStatePath, versionDir, versionsDir, } from "./paths.js";
+export { detectInstallKind } from "./install-kind.js";
+export { activateVersion, pruneOldVersions } from "./activate.js";
+export { writeLocalBinLauncher } from "./launcher.js";
+export { installCliVersionToPrefix, PACKAGE_NAME } from "./npm-prefix-install.js";
+export { compareSemver } from "./semver.js";
+export { readUpdateState, writeUpdateState } from "./update-state.js";
+export { ensurePendingDownload, fetchLatestVersion, isAutoupdaterDisabled, maybeActivatePendingVersion, readCurrentManagedVersion, runManagedCliEntryHooks, scheduleBackgroundUpdateCheck, } from "./updater.js";

package/dist/managed/install-kind.d.ts

@@ -0,0 +1,5 @@
+export type InstallKind = "managed" | "npm-global" | "unknown";
+export declare function detectInstallKind(options?: {
+    whichPath?: string;
+    npmGlobalPrefix?: string;
+}): InstallKind;

package/dist/managed/install-kind.js

@@ -0,0 +1,16 @@
+import { resolveCurrentVersionDir } from "./paths.js";
+export function detectInstallKind(options) {
+    if (resolveCurrentVersionDir())
+        return "managed";
+    const whichPath = options?.whichPath;
+    const prefix = options?.npmGlobalPrefix;
+    if (whichPath && prefix) {
+        const normalizedWhich = whichPath.replace(/\\/g, "/");
+        const normalizedPrefix = prefix.replace(/\\/g, "/").replace(/\/$/, "");
+        if (normalizedWhich === normalizedPrefix ||
+            normalizedWhich.startsWith(`${normalizedPrefix}/`)) {
+            return "npm-global";
+        }
+    }
+    return "unknown";
+}

package/dist/managed/launcher.d.ts

@@ -0,0 +1 @@
+export declare function writeLocalBinLauncher(): void;

package/dist/managed/launcher.js

@@ -0,0 +1,19 @@
+import fs from "node:fs";
+import { localBinDir, localBinLauncherPath } from "./paths.js";
+const LAUNCHER_BODY = `#!/usr/bin/env bash
+set -euo pipefail
+HOME_DIR="\${AGENT_DEALER_HOME:-$HOME/.agent-dealer}"
+CURRENT="$HOME_DIR/current"
+BIN="$CURRENT/node_modules/agent-dealer/dist/bin.js"
+if [ ! -f "$BIN" ]; then
+  echo "agent-dealer: managed install broken (missing $BIN). Re-run: agent-dealer install" >&2
+  exit 1
+fi
+exec node "$BIN" "$@"
+`;
+export function writeLocalBinLauncher() {
+    fs.mkdirSync(localBinDir(), { recursive: true });
+    const target = localBinLauncherPath();
+    fs.writeFileSync(target, LAUNCHER_BODY, { mode: 0o755 });
+    fs.chmodSync(target, 0o755);
+}

package/dist/managed/npm-prefix-install.d.ts

@@ -0,0 +1,16 @@
+export declare const PACKAGE_NAME = "agent-dealer";
+export type NpmSpawn = (args: string[], options: {
+    cwd?: string;
+}) => Promise<{
+    code: number;
+    stderr: string;
+}>;
+export declare function installCliVersionToPrefix(version: string, options?: {
+    npmSpawn?: NpmSpawn;
+}): Promise<{
+    ok: true;
+    dir: string;
+} | {
+    ok: false;
+    error: string;
+}>;

package/dist/managed/npm-prefix-install.js

@@ -0,0 +1,38 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import { cliEntryInVersionDir, partialVersionDir, versionDir, versionsDir } from "./paths.js";
+export const PACKAGE_NAME = "agent-dealer";
+const defaultNpmSpawn = (args, options) => new Promise((resolve) => {
+    const child = spawn("npm", args, {
+        cwd: options.cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        shell: process.platform === "win32",
+    });
+    let stderr = "";
+    child.stderr?.on("data", (chunk) => {
+        stderr += chunk.toString();
+    });
+    child.on("error", (err) => resolve({ code: 1, stderr: err.message }));
+    child.on("exit", (code) => resolve({ code: code ?? 1, stderr }));
+});
+export async function installCliVersionToPrefix(version, options = {}) {
+    const npmSpawn = options.npmSpawn ?? defaultNpmSpawn;
+    const partial = partialVersionDir(version);
+    const finalDir = versionDir(version);
+    fs.mkdirSync(versionsDir(), { recursive: true });
+    fs.rmSync(partial, { recursive: true, force: true });
+    fs.mkdirSync(partial, { recursive: true });
+    const result = await npmSpawn(["install", "--prefix", partial, `${PACKAGE_NAME}@${version}`], {});
+    if (result.code !== 0) {
+        fs.rmSync(partial, { recursive: true, force: true });
+        return { ok: false, error: result.stderr.trim() || `npm install failed (exit ${result.code})` };
+    }
+    const entry = cliEntryInVersionDir(partial);
+    if (!fs.existsSync(entry)) {
+        fs.rmSync(partial, { recursive: true, force: true });
+        return { ok: false, error: `Install succeeded but missing CLI entry: ${entry}` };
+    }
+    fs.rmSync(finalDir, { recursive: true, force: true });
+    fs.renameSync(partial, finalDir);
+    return { ok: true, dir: finalDir };
+}

package/dist/managed/paths.d.ts

@@ -0,0 +1,11 @@
+export declare function agentDealerHome(): string;
+export declare function versionsDir(): string;
+export declare function versionDir(version: string): string;
+export declare function partialVersionDir(version: string): string;
+export declare function currentLinkPath(): string;
+export declare function updateStatePath(): string;
+/** Override with AGENT_DEALER_LOCAL_BIN for tests. */
+export declare function localBinDir(): string;
+export declare function localBinLauncherPath(): string;
+export declare function cliEntryInVersionDir(dir: string): string;
+export declare function resolveCurrentVersionDir(): string | null;

package/dist/managed/paths.js

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export function agentDealerHome() {
+    return process.env.AGENT_DEALER_HOME?.trim() || path.join(os.homedir(), ".agent-dealer");
+}
+export function versionsDir() {
+    return path.join(agentDealerHome(), "versions");
+}
+export function versionDir(version) {
+    return path.join(versionsDir(), version);
+}
+export function partialVersionDir(version) {
+    return path.join(versionsDir(), `.partial-${version}`);
+}
+export function currentLinkPath() {
+    return path.join(agentDealerHome(), "current");
+}
+export function updateStatePath() {
+    return path.join(agentDealerHome(), "update-state.json");
+}
+/** Override with AGENT_DEALER_LOCAL_BIN for tests. */
+export function localBinDir() {
+    const override = process.env.AGENT_DEALER_LOCAL_BIN?.trim();
+    if (override)
+        return override;
+    return path.join(os.homedir(), ".local", "bin");
+}
+export function localBinLauncherPath() {
+    return path.join(localBinDir(), "agent-dealer");
+}
+export function cliEntryInVersionDir(dir) {
+    return path.join(dir, "node_modules", "agent-dealer", "dist", "bin.js");
+}
+export function resolveCurrentVersionDir() {
+    const link = currentLinkPath();
+    try {
+        if (!fs.existsSync(link))
+            return null;
+        return fs.realpathSync(link);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/managed/semver.d.ts

@@ -0,0 +1,2 @@
+/** Semver compare: positive if a > b. */
+export declare function compareSemver(a: string, b: string): number;

package/dist/managed/semver.js

@@ -0,0 +1,12 @@
+/** Semver compare: positive if a > b. */
+export function compareSemver(a, b) {
+    const parse = (value) => value.replace(/^v/, "").split(".").map((part) => Number.parseInt(part, 10) || 0);
+    const left = parse(a);
+    const right = parse(b);
+    for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (diff !== 0)
+            return diff > 0 ? 1 : -1;
+    }
+    return 0;
+}

package/dist/managed/update-state.d.ts

@@ -0,0 +1,7 @@
+export interface UpdateState {
+    checkedAt: string;
+    latest: string | null;
+    pendingVersion: string | null;
+}
+export declare function readUpdateState(): UpdateState | null;
+export declare function writeUpdateState(state: UpdateState): void;

package/dist/managed/update-state.js

@@ -0,0 +1,22 @@
+import fs from "node:fs";
+import path from "node:path";
+import { updateStatePath } from "./paths.js";
+export function readUpdateState() {
+    try {
+        const raw = fs.readFileSync(updateStatePath(), "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            checkedAt: parsed.checkedAt,
+            latest: parsed.latest ?? null,
+            pendingVersion: parsed.pendingVersion ?? null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeUpdateState(state) {
+    const file = updateStatePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}

package/dist/managed/updater.d.ts

@@ -0,0 +1,21 @@
+import { installCliVersionToPrefix } from "./npm-prefix-install.js";
+export declare function isAutoupdaterDisabled(): boolean;
+export declare function fetchLatestVersion(): Promise<string | null>;
+export declare function readCurrentManagedVersion(): string | null;
+export declare function maybeActivatePendingVersion(): {
+    activated: string | null;
+};
+export declare function ensurePendingDownload(latest: string, options?: {
+    installVersion?: typeof installCliVersionToPrefix;
+}): Promise<void>;
+export declare function scheduleBackgroundUpdateCheck(options?: {
+    fetchLatest?: () => Promise<string | null>;
+    installVersion?: typeof installCliVersionToPrefix;
+}): void;
+export declare function runManagedCliEntryHooks(options: {
+    allowActivate: boolean;
+    fetchLatest?: () => Promise<string | null>;
+    installVersion?: typeof installCliVersionToPrefix;
+}): {
+    activated: string | null;
+};

package/dist/managed/updater.js

@@ -0,0 +1,107 @@
+import fs from "node:fs";
+import path from "node:path";
+import { activateVersion } from "./activate.js";
+import { detectInstallKind } from "./install-kind.js";
+import { installCliVersionToPrefix } from "./npm-prefix-install.js";
+import { cliEntryInVersionDir, resolveCurrentVersionDir, versionDir } from "./paths.js";
+import { compareSemver } from "./semver.js";
+import { readUpdateState, writeUpdateState } from "./update-state.js";
+import { fetchLatestPublishedVersion } from "../npm-registry.js";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const PACKAGE_NAME = "agent-dealer";
+export function isAutoupdaterDisabled() {
+    const v = process.env.AGENT_DEALER_DISABLE_AUTOUPDATER?.trim().toLowerCase();
+    return v === "1" || v === "true";
+}
+export async function fetchLatestVersion() {
+    const v = await fetchLatestPublishedVersion(PACKAGE_NAME);
+    return v ?? null;
+}
+export function readCurrentManagedVersion() {
+    const real = resolveCurrentVersionDir();
+    if (!real)
+        return null;
+    return path.basename(real);
+}
+export function maybeActivatePendingVersion() {
+    if (isAutoupdaterDisabled())
+        return { activated: null };
+    if (detectInstallKind() !== "managed")
+        return { activated: null };
+    const state = readUpdateState();
+    const pending = state?.pendingVersion;
+    if (!pending)
+        return { activated: null };
+    const dir = versionDir(pending);
+    if (!fs.existsSync(cliEntryInVersionDir(dir)))
+        return { activated: null };
+    activateVersion(pending);
+    writeUpdateState({
+        checkedAt: state?.checkedAt ?? new Date().toISOString(),
+        latest: state?.latest ?? pending,
+        pendingVersion: null,
+    });
+    return { activated: pending };
+}
+export async function ensurePendingDownload(latest, options = {}) {
+    if (isAutoupdaterDisabled())
+        return;
+    const dir = versionDir(latest);
+    if (fs.existsSync(cliEntryInVersionDir(dir))) {
+        const prev = readUpdateState();
+        writeUpdateState({
+            checkedAt: prev?.checkedAt ?? new Date().toISOString(),
+            latest,
+            pendingVersion: latest,
+        });
+        return;
+    }
+    const install = options.installVersion ?? installCliVersionToPrefix;
+    const result = await install(latest);
+    if (!result.ok)
+        return;
+    const prev = readUpdateState();
+    writeUpdateState({
+        checkedAt: prev?.checkedAt ?? new Date().toISOString(),
+        latest,
+        pendingVersion: latest,
+    });
+}
+export function scheduleBackgroundUpdateCheck(options = {}) {
+    if (isAutoupdaterDisabled() || detectInstallKind() !== "managed")
+        return;
+    const state = readUpdateState();
+    if (state?.checkedAt) {
+        const age = Date.now() - Date.parse(state.checkedAt);
+        if (Number.isFinite(age) && age >= 0 && age < CACHE_TTL_MS)
+            return;
+    }
+    const fetchLatest = options.fetchLatest ?? fetchLatestVersion;
+    void (async () => {
+        try {
+            const latest = await fetchLatest();
+            writeUpdateState({
+                checkedAt: new Date().toISOString(),
+                latest,
+                pendingVersion: readUpdateState()?.pendingVersion ?? null,
+            });
+            if (!latest)
+                return;
+            const current = readCurrentManagedVersion();
+            if (current && compareSemver(latest, current) <= 0)
+                return;
+            await ensurePendingDownload(latest, { installVersion: options.installVersion });
+        }
+        catch {
+            // background only
+        }
+    })();
+}
+export function runManagedCliEntryHooks(options) {
+    const activated = options.allowActivate ? maybeActivatePendingVersion().activated : null;
+    scheduleBackgroundUpdateCheck({
+        fetchLatest: options.fetchLatest,
+        installVersion: options.installVersion,
+    });
+    return { activated };
+}

package/dist/update-check.d.ts

@@ -1,5 +1,6 @@
 type UpdateCheckResult = {
     upgraded: boolean;
 };
+/** npm-global / unknown path — keep TTY prompt behavior. Managed uses hooks instead. */
 export declare function maybeCheckForUpdateOnRun(): Promise<UpdateCheckResult>;
 export {};